anchor.diff:  [[writing-docs-overview]]
   == Overview
   
  -This section contains information about contributing to the Minishift documentation.
  +Minishift documentation is located in the *_docs_* sub-directory of the Minishift repository.
  +The documentation is a mix of auto-generated https://en.wikipedia.org/wiki/Markdown[Markdown] files and manually maintained https://en.wikipedia.org/wiki/AsciiDoc[Asciidoc] files.
   
  -[[section-building-minishift-docs]]
  -== Building Minishift documentation
  +[[contribute-to-docs]]
  +== Contributing to the documentation
   
  -Minishift documentation is located in the `docs` sub-folder.
  -The documentation is a mix of generated https://en.wikipedia.org/wiki/Markdown[Markdown] files and manually maintained https://en.wikipedia.org/wiki/AsciiDoc[Asciidoc] files.
  +Minishift is an open-source project and we welcome contributions. Similar to code
  +contributions, if you want to add or edit Minishift documentation, you can create an
  +issue in our link:https://github.com/minishift/minishift/issues[Github issue tracker] and
  +submit a pull request with the changes.
   
  -If you are adding a new file to the doumentation please update the `_topic_map.yml`  in the root of `docs/source` sub-folder.
  +[[docs-conventions-guidelines]]
  +== Conventions and guidelines
   
  -Per default the documentation is built in a Docker container. This way
  -you avoid having to install all the required dependencies on your
  +Minishift documentation is authored in the link:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference[AsciiDoc] markup format. Since
  +Minishift is closely related to the OpenShift Origin
  +project, we follow the link:https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc[OpenShift Documentation Guidelines]
  +for tagging, formatting, and structure wherever possible.
  +
  +The documentation source structure follows a modular format, where each file is called
  +a _topic_ and each topic is stored under a sub-folder based on the relevant category, such as
  +getting started, using Minishift, or command reference.
  +
  +TIP: You can check out the link:https://raw.githubusercontent.com/minishift/minishift/master/docs/source/developing/writing-docs.adoc[raw file]
  +of this topic or other existing Minishift topics to see examples of how the information is structured and which tags to use.
  +
  +[[common-conventions]]
  +=== Commonly-used conventions
  +
  +- Each file must contain a topic metadata header with a top-level heading followed by required AsciiDoc variable declarations. See
  +the link:https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc#topic-metadata[topic metadata]
  +section in the OpenShift documentation guidelines for more information.
  +
  +- Links to another location within an AsciiDoc topic or between AsciiDoc topics are called cross-references and should use the _xref_ notation.
  +See the link:https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc#internal-cross-references[internal cross-references]
  +section of the OpenShift documentation guidelines for more information and examples.
  +
  +- Each section heading must be preceded by a unique anchor ID, to help make sure that
  +cross-references resolve to the correct section. The anchor ID text should match the title
  +as much as possible. See the link:https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc#unique-ids[unique IDs]
  +section of the OpenShift documentation guidelines for more information and examples.
  +
  +[[adding-new-topic]]
  +=== Adding a new topic
  +
  +If you are adding a new topic to the documentation library, you must also
  +update the navigation in the following ways:
  +
  +- Add an entry to the relevant *_index.adoc_* file for that topic. For example, if you
  +add a new topic in the *_docs/source/using/_* directory, you must update the *_docs/source/using/index.adoc_*
  +file in the same directory.
  +
  +- Add an entry to the *__topic_map.yml_* in the *_docs/source_* sub-folder. The entry must
  +contain the topic title and the file name.
  +
  +Make sure to add the new topic in the same order in all of the locations.
  +
  +[[building-docs]]
  +== Building the documentation
  +
  +By default, the documentation is built in a Docker container. This way
  +you do not need to install all the required dependencies on your
   development machine. All you need is a running Docker daemon. In case
  -you don't have one, use Minishift itself. For further information refer to
  -link:../command-ref/minishift_docker-env{outfilesuffix}[`minishift docker-env`].
  +you don't have one, use Minishift itself. For more information, see
  +xref:../using/docker-daemon.adoc#reusing-docker-daemon[reusing the Docker daemon].
   
  -To build the Docker image, run:
  -
  -----
  -$ make build_docs_container
  -----
  -
  -To generate the documentation into the directory `docs/build`, run:
  +To generate the documentation into the *_docs/build_* directory, run:
   
   ----
   $ make gen_docs
  
positive.code: $ rake build
  ----
  
  If the build completes successfully, the site is available under _preview/openshift-origin/latest/welcome/index.html_.
  
negative.code: $ make serve_docs
  ----
  
  The `make serve_docs` command builds and generates a live-preview of the documentation.
  You can access the documentation by browsing to _http://<IP-of-Docker-daemon>:4567_.
  
  If you encounter issues with the local staging of the documentation, you can run the following
  command to remove all build artefacts:
  
  ----
  $ make clean_docs
  ----
  
  [[integration-with-docs-openshift-org]]
  == Integration with docs.openshift.org
  
  The Minishift documentation is deployed on _docs.openshift.org_ under
  link:https://docs.openshift.org/latest/minishift[https://docs.openshift.org/latest/minishift].
  
  To integrate with _docs.openshift.org_, we deliver a tarball that contains the Minishift AsciiDoc files as well as some link:http://www.asciibinder.org/[AsciiBinder] metadata files.
  This tarball is generated with a Jenkins job on link:https://ci.centos.org/job/minishift-docs[CentOS CI] and is triggered as part of a xref:./releasing.adoc#cut-release[release].
  
  [[manually-building-openshift-docs]]
  === Manually building the OpenShift documentation
  
  To view the Minishift documentation integrated into the OpenShift documentation, you can follow the following steps.
  
  [NOTE]
  ====
  - Before you start, you need to check out the link:https://github.com/openshift/openshift-docs.git[openshift-docs] GitHub repository.
  You need all the tooling to build openshift-docs.
  See the link:https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/tools_and_setup.adoc[Install and set up the tools and software] section, which is part of the _openshift-docs_ repository.
  
  - Make sure that the `rake build` commands succeeds before integrating the Minishift documentation.
  ====
  
  . In the local Minishift repository, build the Minishift documentation tarball.
  
  ----
  $ make gen_adoc_tar
  ----
  
  After the build completes there will be a *_minishift-adoc.tar_* file in the *_docs/build_* directory of the local Minishift repository.
  
  . In the local openshift-docs repository, run the following commands:
  
  ----
  $ mkdir minishift
  