Skip to content

Style and Structure Quick Reference

Style and structure guidelines should be followed as closely as possible to ensure consistency throughout the documentation. Consistency in styles and standards improve the user experience by allowing them to easily search, scan, and locate information.

Intro paragraphs

Intro paragraphs, or overviews, aim to provide readers with a basic understanding of tasks, features, or concepts.

Intro paragraph guidelines:

  • Keep it brief and at a high-level for the opening paragraph; sub-sections should be used to cover related topics in more depth.
  • Avoid adding statements about what the topic covers unless essential. Phrases like "This topic describes..." are usually redundant since the title and table of contents, which is derived from section headings, should sufficiently convey the scope of the topic.
  • Do not use preview lists (a list of topics or heading titles). Doing so repeats information already available in the table of contents.
  • Do not add a title, such as "Overview," to the opening paragraph. The opening paragraph should be a reflection of the topic's title.
  • Avoid adding filler content. If the title is self-explanatory and the content adds no value, leave it out. For example, "Review a Pull Request" is a procedure with a meaningful title; an introductory paragraph is probably unnecessary.

Headings and subheadings

Headings and subheadings should describe the type of information contained in the sections that follow. This helps users scan documents to quickly find the information they need.

As a general guideline, you should use no more than three levels of headings. While the use of deeper levels may be necessary on occasion, it should be the exception. If you find that you require several levels within a single topic or section, consider whether you're addressing too many differing topics at once. Often, those sections can be reorganized in a more logical manner, avoiding the need for readers to navigate so deep within a section.

Headings, other than document titles, should use sentence case capitalization.

Heading examples
Create GitHub Personal Access Tokens Document title (H1, title case)
Configure permissions Section heading (H2, sentence case)
To create a Pull Request Procedure heading (H4, sentence case)

Procedures

Procedures should be in a numbered list when they contain two or more steps. Single-step procedures should follow the same guidelines as multi-step procedures, but instead use a bulleted list.

Procedure guidelines:

  • Use an infinitive phrase ending in a colon to introduce the procedure.
  • Use heading level four (H4) for procedure headings.
  • Avoid adding explanatory text after the procedure heading.
  • When used, notes should be added to the applicable step, rather than the end of the procedure.
  • Use bold to call out UI elements (sections, menus, lists, buttons, etc).
  • Avoid using step results (statements that tell users what occurs when they complete a step). Only include step results if a resulting action is unexpected or confusion is likely.
  • If a procedure contains sub-steps, use a bulleted list instead of a numbered/lettered list.

Example

To create a GitHub personal access token:

  1. Ensure you are logged in to GitHub.
  2. Go to the New personal access token page.
  3. Choose a token expiration length from the Expiration list.
  4. Click the Generate Token button
  5. Copy the new token to the clipboard, then save it.

Text formatting conventions

Standardized formatting provides visual cues that help guide readers through the content. When consistently applied, formatting contributes to the overall usability, scanability, and effectiveness of a document.

Bold font

Apply bold font to the following:

  • UI elements: buttons, icons, lists, menus, fields, text boxes, sections, areas, or any other UI element that has a title, label, or tooltip. Bold face font is most frequently applied when documenting procedures.
  • Keyboard keys
  • In procedure headings, when not using H4
  • Items in a list, if the items contain additional descriptions

Italic font

Apply italics when you introduce and define a term for the first time.

Monospace font

Apply monospace font to the following:

  • Variable names: roleName
  • File names: index.md
  • Form or field text
  • Directory paths: ./infrastructure/app
  • Tags: <workload> or <service>
  • Role names: SAML-<workload>-Engineer
  • Domain names or FQDNs (unless they are linked): ghe.company.com
  • Resources or policy names: resourceID or policyName
  • Any other relevant scripts or commands used in code editors or command-line interfaces.

Codeblocks

Use codeblocks for the following:

  • Complete lines of code, including full single lines
  • Markup language samples, YAML/JSON/XML/etc.
  • Error messages
  • GIT diffs
sde login --workload=<workload> --role=<role> --env=<env> --version=2 --assume=Engineer

const service = new abcBlueGreenApplicationLoadBalancedFargateService(this, 'FargateService', {
      serviceName: APP_NAME,
      cluster: cluster,
      ...
      ...
      enableExecuteCommand : true
    })

Admonishments

Use Info, Note, and Warning admonishments to highlight important supplemental or essential information. Admonishments should be used sparingly, as overuse diminishes their significance.

Info

Use when providing non-essential, but useful, information that improves efficiency or understanding. Use also for shortcuts and secondary methods of performing a function or task. Use Tip in place of Info when appropriate.

Note

Use to highlight important information, such as a prerequisite or requirement.

Warning

Warnings should only be used when conveying potential risk or when harm can occur as a result of an action or inaction. For example, irreversible data loss or corruption, performance impact, or security risks.

When directing readers to additional information, use "For more information, see <link-to-topic>." The link text should reflect the title of the topic. Topic titles are usually intuitive on their own; however, if necessary for clarity, briefly state what the topic is about. For example: "For more information about <XYZ>, see <link-to-topic>."

Ensure that links have meaningful text that inform readers where they will be redirected when they click it. For example, "In Service Now, go to the Request Cloud Platform AWS Access page" provides more clarity than "Click here for AWS Access."

When linking to external documentation, identify the 3rd party and use the title of the document for the link text. For example, "For more information, see SonarQube: Operating the server."

Tip

When URLs and links are long or repeated on the same page, consider creating an alias list. Doing so promotes content reuse and helps maintain the readability of the markdown.