Article format

The docs site strives to avoid articles that are excessively short or long. It’s okay to have some short pages and some long pages in the docs site because the goal is to create pages that users read and learn from. However, very short articles provide little value or discoverability in the docs site search.

Articles should be at least 200 words long, not including ordered lists of links.

Steps in how-to articles count toward the 200-word total. If the article is included in the sidebar with articles nested under it, include more than just links to the nested articles.

If an article can’t reach at least 200 words under these conditions, consider whether the content should be in its own article at all. Articles that are shorter than 200 words are usually uninformative.

If an article is very long, split it into multiple articles if possible. Do not split the article solely to create shorter articles. If a long article does discuss one topic, then it should remain one article regardless of length.

The AsciiDoc frontmatter contains metadata keys and values. It appears at the top of each document. Docs team members can view the documentation repository for full details on the frontmatter fields.

Use the subtitle field in the frontmatter when all of the following are true:

Use sentence-style capitalization for titles, subtitles, and section headers.

Do not start a how-to title, subtitle, or section header with "How to." Do not start a title, subtitle, or section header with a gerund.

If a product name appears in the title or subtitle, treat it as a proper noun. Capitalize the term as stated in the glossary.

Examples:

Consult the Google Developer Documentation Style Guide for more information on headers and titles.

Use section headers to divide an article’s content into hierarchical sections. In Asciidoc, the H1 HTML tag corresponds to =, H2 corresponds to ==, and so on. The docs site automatically creates a table of contents from the section headers.

Do not use the H1 tag in your documents. The H1 tag is reserved for the article title.

Use H3 and more nested tags wisely.

Do not use bolded text to title a section.

Do not use numbers as numerals to lead an article title or section header unless a product name begins with a number.

If an item that would typically be formatted in code format appears in a section header, do not use code formatting if the item appears at the beginning of the section header. It’s okay to use code format if the item appears elsewhere in the section header. If possible, reword the section header so the code-formatted item does not appear at the beginning.

Asciidoc supports admonition syntax, which calls out the text on a separate line with a note. Learn more about admonition syntax.

Use admonition syntax wisely. Using too many admonitions dulls their impact.

To use an admonition, use the admonition type in capital letters followed by a colon (:).

The admonition displays as follows.

The TIP.faq admonition is custom-built for the Lucidworks docs site. Its syntax differs from standard admonitions.

Tables and lists are two ways to lay out similarly structured information on a single topic.

Consult the Google Developer Documentation Style Guide for information on when to use a table or a list. In general:

Use a table to display a group of items that consist of three or more items. Consult the Asciidoc documentation for more information on Asciidoc table syntax.

Use an ordered list when enumerating steps to be performed in a specific order. Use + in between lines to use mulitple lines within one list item or to include an admonition in between steps while maintaining the numbering scheme.

Use an unordered list when listing items that are not in a sequence.

Use a description list instead of headings for a group of items that consist of an item and a description. Description lists display as lists without the preceding character of an ordered or unordered list.