diff --git a/styleguide/modules/ROOT/pages/ordered-list.adoc b/styleguide/modules/ROOT/pages/ordered-list.adoc index 0e7e26e..74c5a01 100644 --- a/styleguide/modules/ROOT/pages/ordered-list.adoc +++ b/styleguide/modules/ROOT/pages/ordered-list.adoc @@ -2,7 +2,26 @@ Use an ordered list when you have a procedure, task, or collection of items where the order matters. -Use a period (.) to render an item as an ordered list item. +For example: + +**** +. Go to menu:Data Tools[Search]. +. Click btn:[Create Search Index]. + +The user would not be able to click the *Create Search Index* button if they did not go to menu:Data Tools[Search], first. + +The order of the steps matters. +**** + +You must use an ordered list to write out the steps in a xref:writing-procedures.adoc[procedure topic]. +It's okay to have a procedure that only contains 1 step. + +You can also use an ordered list in a xref:writing-concepts.adoc[concept topic] if: + +* The order of things in the list matters. +* You're describing a series of procedures or larger tasks a user must complete to accomplish a goal. + +Use a period (`.`) to render an item as an ordered list item. The number of periods sets the depth of the list item. For more information about how to format an ordered list in Antora, see xref:home:contribute:basics.adoc#ordered-lists[Ordered Lists] in the Contributing to the Documentation guide. \ No newline at end of file diff --git a/styleguide/modules/ROOT/pages/placeholders.adoc b/styleguide/modules/ROOT/pages/placeholders.adoc index 4d08e13..557898d 100644 --- a/styleguide/modules/ROOT/pages/placeholders.adoc +++ b/styleguide/modules/ROOT/pages/placeholders.adoc @@ -1,9 +1,32 @@ = Code Placeholders -When you need to add a placeholder value to a xref:examples.adoc[code example]: +The type of placeholder you add to code depends on the type of xref:examples.adoc[code example] you're including. + +== curl and Shell Placeholders + +When you need to add a placeholder value to a curl or other shell code example: * Write the placeholder name in capital letters. * Use a `$` before the placeholder name. -* Use underscores to separate words. +* Use underscores (`_`) to separate words. + +For example, `$DATABASE_NAME`. + +== REST API Path Attribute Placeholders + +When you need to add a placeholder value to a path attribute for a REST API example: + +* Write the placeholder name in capital letters. +* Surround the placeholder name in curly braces (`{}`). +* If necessary, use underscores (`_`) to separate words. + +For example, `{PORT}`. + +== Other Placeholders + +If your code format does not support a value using curly braces (`{}`) or a `$` prefix, then you must: + +* Write the placeholder name in capital letters. +* Surround the placeholder name in angled brackets (`<>`). -For example, `$DATABASE_NAME`. \ No newline at end of file +For example, ``. \ No newline at end of file diff --git a/styleguide/modules/ROOT/pages/unordered-list.adoc b/styleguide/modules/ROOT/pages/unordered-list.adoc index a9f4b52..68daf88 100644 --- a/styleguide/modules/ROOT/pages/unordered-list.adoc +++ b/styleguide/modules/ROOT/pages/unordered-list.adoc @@ -3,12 +3,24 @@ Use an unordered or bulleted list when you have a collection of three or more things and the order of the items does not matter. These items could be nouns, phrases, or topics. +For example: + +**** +* This is a list item +** This is a sub-item +**** + If you only have two items in your list, it's okay to just write it out in a sentence. -Use an unordered list when writing prerequisites or a See Also section in your documentation. -Use an unordered list for prerequisites and the See Also section even if it contains only a single item. +Use an unordered list when: + +* Writing a prerequisites section in your documentation. +* Writing a See Also section in your documentation. +* Structuring the `nav.adoc` file in a documentation module. + +NOTE: Use an unordered list for prerequisites and the See Also section even if it contains only a single item. -Use an asterix (*) to render an item as an unordered list item. +Use an asterix (`*`) to render an item as an unordered list item. The number of asterixes sets the depth of the list item. For more information about how to format an unordered list in Antora, see xref:home:contribute:basics.adoc#unordered-lists[Unordered Lists] in the Contributing to the Documentation guide. \ No newline at end of file diff --git a/ui-ux/modules/ROOT/pages/good-content.adoc b/ui-ux/modules/ROOT/pages/good-content.adoc index 45ed53d..4d8a003 100644 --- a/ui-ux/modules/ROOT/pages/good-content.adoc +++ b/ui-ux/modules/ROOT/pages/good-content.adoc @@ -21,7 +21,7 @@ We write content that's factually correct, always. We use the same word or words to mean the same thing. We follow industry standards and conventions, but also our own. -(That's why we maintain a xref:styleguide:ROOT:wordlist.adoc[word list]). +(That's why we maintain a xref:styleguide:ROOT:word-list.adoc[word list]). We adhere to our xref:voice.adoc[voice and tone standards].