anchor.diff: -= Documentation guidelines 
  += Documentation guidelines
   :icons:
   :toc: macro
   :toc-title:
  
positive.code: 
  $$*software package*$$
  
  a|*HTTPD* 
  
  *NetworkManager*
  
  
negative.code: |Try to be as descriptive as possible with the topic title or section headings without making them unnecessarily too long. Most importantly, we use title case in all topic titles and section headings. See http://titlecase.com/ for more information.
  |===
  
  == Product name & version attributes
  
  When possible, generalize references to the product name and/or version using
  the `{product-title}` and/or `{product-version}` attributes. These attributes
  are pulled from distro mapping definitions in the
  https://github.com/openshift/openshift-docs/blob/master/_distro_map.yml[distro_map.yml]
  file.
  
  The `{product-title}` comes from the first `name:` field in a distro mapping,
  while the associated `{product-version}` comes from the `name:` fields on any
  `branches:` defined.
  
  How these attributes render is dependent on which distro and branch build you
  are viewing. The following table shows the current slate of distros and the
  possible values for `{product-title}` and `{product-version}`.
  
  [options="header"]
  |===
  |Distro |`{product-title}` |`{product-version}`
  
  |`openshift-origin`
  |OpenShift Origin
  |Latest
  
  |`openshift-enterprise`
  |OpenShift Enterprise
  |3.1, 3.0
  
  |`openshift-dedicated`
  |OpenShift Dedicated
  |3.1, 3.0
  
  |`openshift-online`
  |OpenShift Online
  |Latest
  |===
  
  For example:
  
  ----
  You can deploy applications on {product-title}.
  ----
  
  This is a safe statement that could appear in probably any of the builds, so an
  https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/contributing.adoc#conditional-text-between-products[ifdef/endif
  statement] is not necessary. For example, if you were viewing a build for the
  `openshift-enterprise` distro (for any of the distro-defined branches), this
  would render as:
  
  "You can deploy applications on OpenShift Enterprise."
  
  And for the `openshift-origin` distro:
  
  "You can deploy applications on OpenShift Origin."
  
  Considering that we use distinct branches to keep content for product versions
  separated, global use of `{product-version}` across all branches is probably
  less useful, but it is available if you come across a need for it. Just consider
  how it will render across any branches that the content appears in.
  
  == Links, hyperlinks, and cross references
  Links can be used to cross-reference internal topics, or send customers to external information resources for further reading.
  
  === Internal Cross-References
  Whenever possible the link to another topic should be part of the actual sentence. Avoid creating links as a separate sentence that begins with "See [this topic] for more information on x".
  
  [NOTE]
  ====
  Use the relative file path (from the file you are editing, to the file you are linking to), even if you are linking to the same directory that you are writing in. This makes search and replace operations to fix broken links much easier.
  
  For example, if you are writing in *_architecture/core_concepts/deployments.adoc_* and you want to link to *_architecture/core_concepts/routes.adoc_* then you would need to include the path back to the first level of the topic directory:
  
  ----
  link:../../architecture/core_concepts/routes.adoc
  