anchor.diff:  $ make serve_docs
   ----
   
  -The latter will start the https://middlemanapp.com[Middleman] server on port 4567.
  -You can access the rendered documentation by browsing to http://<IP of Docker daemon>:4567.
  +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_.
   
  -[[section-deploying-minishift-docs]]
  -== Deploying Minishift documentation
  +If you encounter issues with the local staging of the documentation, you can run the following
  +command to remove all build artefacts:
   
  -The Minishift documentation is deployed on _docs.openshift.org_.
  -To integrate with this site we deliver a tarball containing the Minishift asciidoc files as well as some link:http://www.asciibinder.org/[AsciiBinder] meta data.
  +----
  +$ make clean_docs
  +----
   
  -This tarball can be built using:
  +[[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
   ----
   
  -Once the build completes there will be a _minishift-adoc.tar_ in the _docs/build_ directory
  -of your checkout.
  +After the build completes there will be a *_minishift-adoc.tar_* file in the *_docs/build_* directory of the local Minishift repository.
   
  -How this tarball is integrated into the docs.openshift.org site build is described in
  -<<section-building-openshift-docs>>.
  -
  -[[section-building-openshift-docs]]
  -=== Building OpenShift documentation
  -
  -To start with you need a checkout of the link:https://github.com/openshift/openshift-docs.git[openshift-docs]
  -GitHub repository. You need all the tooling to build openshift-docs. Refer to
  -link:https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/tools_and_setup.adoc[Install and set up the tools and software] which is part of the openshift-docs repository.
  -
  -Once you can successfully run `rake build` in your openshift-docs checkout, you can integrate the
  -Minishift documentation.
  -
  -Start with building the documentation tarball as described in <<section-deploying-minishift-docs>>,
  -then follow these steps (assuming you are in the directory of your openshift-docs checkout):
  +. In the local openshift-docs repository, run the following commands:
   
   ----
   $ mkdir minishift
  
positive.code: [[writing-docs-overview]]
  == Overview
  
  This section contains information about contributing to the Minishift documentation.
  
  [[section-building-minishift-docs]]
  == Building Minishift 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.
  
  If you are adding a new file to the doumentation please update the `_topic_map.yml`  in the root of `docs/source` sub-folder.
  
  Per default the documentation is built in a Docker container. This way
  you avoid having 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`].
  
  To build the Docker image, run:
  
  ----
  $ make build_docs_container
  ----
  
  To generate the documentation into the directory `docs/build`, run:
  
  ----
  $ make gen_docs
  
negative.code: Errno::EACCES: Permission denied @ dir_s_mkdir - build
  ----
  
  In this case you need to build the container with a different user ID.
  This will ensure that the _docs_ user in the container will be able to create files and directories.
  
  ----
  $ make build_docs_container IMAGE_UID=$(id -u)
  ----
  
  ====
  
  To build and serve the documentation for editing, run:
  