Introduction

Follow these guidelines to ensure consistent formatting of all external documentation.

Section Headings

Asciidoctor makes all section headings into anchors.

• Try to make section headers as specific as possible, so the anchors are descriptive in case when sharing links to specific sections of the docs.
  • Don't: == Installing
  • Do: == Installing <feature_name>

Each topic should be in it's own .adoc file with appropriate header settings. For document reuse, start each file's heading sections at level two (== Title). The jbake template will adjust the level to the appropriate setting in the target document. 

Paragraphs

To help with editability, each sentence should be on a new line. Asciidoctor renders them as a single paragraph, until a blank line signals a new paragraph. This makes it easier to browse and make corrections. A possible exception is within tables or lists where it may affect the readability of the table syntax.

Manual anchors can also be created to link to any arbitrary spot in the text and should follow the same conventions in most cases. Asciidoctor anchors have a syntax as follows:

[[_manual_anchor]]Anchor Text

• The square brackets define an anchor.
• Use the leading underscore instead of the prefix because this anchor is only a destination, not a link.
• The anchor text is arbitrary. Manual anchors should usually be used for captions or the start of a relevant 

Special Formatting Conventions

Writing About Procedures

Maintain consistency when writing instructions for procedures. 

Admin Console Procedures

Start any installation or configuration procedures done through the admin console in the same way.

• Always start with "Navigate to the *${admin-console}*." as the first step.
• Use a numbered list.
• Put only one action per step.
• End each step with a period, even if not a complete sentence.
• Prefer "Select" over "Click," or  "Click on".
• Use the exact wording for text links, buttons, or icons.
  • For unnamed icons, use the tool tip description.

Command Console Procedures

Intrigue Procedures

Writing Explanations

Formatting Tables & Diagrams

Introduce the table or diagram to explain the information described in the table. Links should be to the section containing the table, or to an anchor added to the introduction, instead of directly to the block. 

• Give the table or diagram a specific, descriptive title/caption.
  • Asciidoctor syntax for a caption is a leading . with no space: .Caption Text .
• Use Asciidoctor-diagram Ditaa syntax formatted tables when possible. 
  • Avoid using ${branding} substitutions, as they may not resolve correctly within the diagram in custom distributions.
  • Default colors are cDEF, c369, and cCCC.
    • Accent colors to use sparingly:  c5F5, cF55, c555
       

Tables

Tables can be formatted in a few ways, but to maintain consistency, these conventions should be followed.

• Start with a title, if applicable.

.Dot Title

• Within square brackets, define the number of columns, and the relative width of each column. Add a header, if appropriate. (while it is possible to define a number of equally-columns with [cols="3"], in practice, this syntax often has problems with dropping table rows

[cols="1,3,1" options="header"]

• On the next line, add the table delimiter.

|===

• Keep each cell on a separate line with a blank line between rows, and close with another table delimiter.

 |cell 1
 |cell 2
 |cell 3

 |cell 4
 |cell 5
 |cell 6

|===

• If Asciidoctor syntax is needed within a table cell, prepend an a character before the | that starts the cell. 
• See Asciidoctor documentation for advanced topics, such as spanning columns or row. 
  
  

.Table title
[cols="1,3,1" options="header"]
|===
|Header 1
|Header 2
|Header 3

|cell 1
|cell 2
a|cell 3
* list item 1
* list item 2

|===

Diagrams

[ditaa,diagram-file-name,png]
....
+--------+
|Object 1|
|cDEF    |
+--------+
....

Formatting Code Blocks

Short blocks of code, system attributes and properties, and file names/extensions/directories should be surrounded by backticks to render as monospace. Longer code samples should be set off in code blocks as follows. Adding an anchor is optional, but encouraged. Anchors should be unique to not conflict with anchors in other sections.

Make a code block for anything longer than a single line. Short snippets of less than one line can be formatted monospace inline. 

Introduce the code block and the context for it. Links should be to the section containing the code block, or to an anchor added to the introduction, instead of directly to the block. 

• Provide a descriptive caption
  
  • Asciidoctor syntax for a caption is a leading . with no space: .Caption Text .
• Specify the language, if possible, to enable syntax highlighting. See list of supported languages: CodeRay.
  • Example: [source, java]
• If more than five lines, add line numbers with linenums
  • [source, javascript, linenums]
  • Exception: don't use line numbers for blocks of console input / output.

.[[anchor]]Caption or Description Line
[source,language,linenums]
----
// code ....
----