diff --git a/doc_guidelines.adoc b/doc_guidelines.adoc new file mode 100644 index 000000000000..c311f60b383d --- /dev/null +++ b/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: <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:.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 /images +2. In the topic document, use this format to link to an image: + +---- +image:[image] +---- + +You only need to specify . 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]##$$ +a|This represents text that a user must replace with an actual value. For example: + +`rhc app delete [replaceable]##` \ No newline at end of file