Adding doc guidelines topic

doc_guidelines.adoc

@@ -0,0 +1,304 @@
+= Documentation Guidelines [DRAFT]
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:toc:
+:toc-placement!:
+:toc-title: Topics Covered
+:description: These are basic guidelines for creating technical documentation for OpenShift.
+
+toc::[]
+
+== Directory and file naming conventions
+
+All topic directory groups and topic filenames must be lowercase in order for the build system work correctly, as shown in the following example:
+
+....
+/
+/topic_dir
+/topic_dir/topic_1.adoc
+/topic_dir/topic_2.adoc
+/topic_dir/topic_3.adoc
+....
+
+== Topic Files
+
+Every topic file should contain the following metadata at the top, with no line spacing in between, except where noted:
+
+----
+= Document/Topic Title                                          <1>
+{product-author}                                                <2>
+{product-version}                                               <3>
+:data-uri:                                                      <4>
+:icons:                                                         <5>
+:toc:                                                           <6>
+:toc-placement!:                                                <7>
+:toc-title: Topics Covered                                      <8>
+:description: <Brief description of content for search>         <9>
+-----------intentional blank line--------------
+toc::[]                                                         <10>
+----
+
+<1> Human readable title of document/topic title line (notice the '=' top-level header)
+<2> AsciiDoctor attribute for product author and gets dynamically replaced 
+<3> AsciiDoctor attribute for product version and gets dynamically replaced 
+<4> AsciiDoctor attribute to embed all images directly in the HTML 
+<5> AsciiDoctor attribute for icons used in admonitions and such (TIP, NOTE, WARNING, etc.)
+<6> Adds a table of contents (TOC).
+<7> Overrides the default placement of TOC.
+<8> Overrides the default title of TOC.
+<9> Brief description or synopsis of the document/topic to help with Google search.
+<10> Placement of the TOC.
+
+After the heading block and a single whitespace line, you can include any content for the topic.
+
+[NOTE]
+====
+Section headers within the topic must be level 2 ( == ) or lower.
+====
+
+If using section anchors, they must be all lowercase letters, with no line spaces between the anchor and the section title:
+
+----
+[[section_anchor_name]]
+=== Section Title
+----
+
+== Links, hyperlinks, and cross references
+
+If you want to link to a different website, use:
+
+----
+http://othersite.com/otherpath[friendly descriptor]
+----
+
+If you want to link to another topic in the same topic group directory:
+
+----
+link:<filename>.html[friendly title]
+----
+
+Be aware of the use of '.html' in the link. Do not use the '.adoc' file extension because the link is to the resulting HTML file. 
+
+There probably are two scenarios for linking to other content: 
+
+1. Link to another topic file that exists in a separate topic group, or directory.
+2. Link to another topic file that exists in the same topic group, or directory.
+
+The following examples use the example directory structure shown here:
+....
+/
+/foo
+/foo/bar.adoc
+/baz
+/baz/zig.adoc
+/baz/zag.adoc
+....
+
+If you are working on bar.adoc and you want to link to zig.adoc, do it this way:
+
+----
+link:../baz/zig[see the ZIG manual for more]
+----
+
+Note there is no suffix with the filename. (.adoc or .html)
+
+If you are working on zig.adoc and want to link to zag.adoc, do it this way:
+
+----
+link:zag[comment]
+----
+
+This type of linking should be sufficient in most cases. However, you can also link to a subtopic within a topic file:
+
+----
+link:../baz/zig/#subtopic
+----
+
+If you want to link to an image:
+
+1. Put it in <topic_dir>/images 
+2. In the topic document, use this format to link to an image:
+
+----
+image:<name_of_image>[image]
+----
+
+You only need to specify <name_of_image>. The build mechanism automatically specifies the file path. 
+
+If you want to build a link from a URL without changing the text from the actual URL, just print the URL without adding a [friendly text] block at the end; it will automatically be rendered as a link.
+
+== Conditional text between products
+OpenShift documentation uses the AsciiDoc `ifdef/endif` macro to conditionalize document segments for specific OpenShift distributions down to the single-line level.
+
+The supported distribution attributes used with the OpenShift build mechanism are: 
+
+* _openshift-origin_
+* _openshift-online_
+* _openshift-enterprise_
+
+These attributes can be used by themselves, or in conjunction to conditionalize text within a topic document.
+
+Here is an example of this concept in use:
+
+....
+This first line is unconditionalized, and will appear for all versions.
+
+ifdef::openshift-online[]
+This line will only appear for OpenShift Online.
+endif::[]
+
+ifdef::openshift-enterprise[]
+This line will only appear for OpenShift Enterprise.
+endif::[]
+
+ifdef::openshift-origin,openshift-enterprise[]
+This line will appear for OpenShift Origin and Enterprise, but not for OpenShift Online.
+endif::[]
+....
+
+
+Note that the following limitations exist when conditionalizing text:
+
+1. The `ifdef/endif` blocks have no size limit, however they should not be used to conditionalize an entire topic. If an entire topic file is specific to a given OpenShift distribution, refer to the Document Set Metadata section for information on how to conditionalize at the whole-topic level.
+
+2. The `ifdef/endif` blocks cannot be nested. In other words, one conditional block cannot contain other conditional blocks.
+
+== Formatting
+
+For all of the system blocks including table delimiters, use four characters. For example:
+
+....
+|=== for tables
+---- for code blocks
+....
+
+=== Code blocks
+
+For all code blocks, you must include an empty line above a code block.
+
+Acceptable:
+
+....
+Lorem ipsum
+
+----
+$ lorem.sh
+----
+....
+
+Not acceptable:
+
+....
+Lorem ipsum
+----
+$ lorem.sh
+----
+....
+
+Without the line spaces the content is likely to be not parsed correctly.
+
+Also, if you want to render some code inline, use backticks:
+
+....
+"The file can be found at `/dev/null` on your host."
+....
+
+Which renders as:
+
+"The file can be found at `/dev/null` on your host."
+
+=== Lists
+Lists are created as shown in this example:
+
+....
+.  Item 1 (2 spaces between the period and the first character)
+
+.  Item 2
+
+.  Item 3
+....
+
+This will render as such:
+
+.  Item 1
+
+.  Item 2
+
+.  Item 3
+
+If you need to add any text, admonitions, or code blocks you need to add the continuous +, as shown in the example:
+
+....
+.  Item 1
++
+----
+some code block
+----
+
+.  Item 2
+
+.  Item 3
+....
+
+This renders as shown:
+
+.  Item 1
++
+----
+some code block
+----
+
+. Item 2
+
+. Item 3
+
+=== Examples
+
+Use the following format when showing examples:
+
+....
+.Example Title
+----
+Example text here
+----
+....
+
+
+== Admonitions
+
+Admonitions such as notes and warnings are formatted as shown:
+
+....
+[ADMONITION]
+====
+Text for admonition
+====
+....
+
+== Quick markup reference
+
+[cols="4,7"]
+|===
+|Markup |Description
+
+|$$`rhc app create`$$
+|Inline commands, for example:
+
+Use the `rhc app create` command to create a new application.
+
+|$$[parameter]#MAX_GEARS#$$
+|System or software parameters:
+
+Set the [parameter]#MAX_GEARS# parameter to the desired value.
+
+|$$[userinput]#value#$$
+|Values that a user is asked to enter:
+
+Type [userinput]#Yes# when prompted.
+
+|$$[replaceable]#<Name>#$$
+a|This represents text that a user must replace with an actual value. For example:
+
+`rhc app delete [replaceable]#<App_Name>#`