Plixer Product Documentation Style Guide

Table of Contents

1. Introduction
2. Headings
3. Style and Tone
4. Stylization
5. Terms and Conventions
6. Writing Instructions

---

Introduction

To be added later

---

Headings

1. Define tab headings (H1) with = (overline and underline)
   Example:

    =========  
    Heading 1  
    ========= 
   

2. Tab headings should be capitalized as standard titles
   Example:

    How to Underline a Tab Heading
   

3. Underline section headings (H2) within a tab with =
   Example:

    Heading 2  
    =========
   

4. Underline subsection headings (H3) with -
   Example:

    Heading 3  
    ---------
   

5. Underline subsequent headings with ^ (H4) and " (H5)
   Example:

    Heading 4
    ^^^^^^^^^
   

6. Capitalize only the first letter of headings beyond H1
   Example:

    Overlines and underlines
   

7. Ensure that overlines and underlines match the heading's character length

---

Style and Tone

1. Use clear, straightforward language.
2. Keep sentence and paragraph length to a minimum.
3. Avoid unnecessary use of the passive voice.
4. Frame instructions as imperatives, but do not use second-person pronouns.
5. Use the third person when not directly addressing the reader (e.g., when describing a product or its features).

---

Stylization

1. Capitalize Plixer product names outside of case-sensitive contexts (e.g., usernames, passwords, etc.). Example:

   Connect to the Plixer Replicator using admin as the username and replicator as the password.

2. Capitalize product-specific names or terms.

3. Italicize product names and product-specific names or terms when they are first mentioned.

4. Use boldface emphasis when referring to UI elements in instructions (e.g., tabs, buttons, etc.).
   Example:

   Click on the Exporters tab to view all current Exporters.

5. Italicize menu selections in instructions (e.g., radio buttons, dropdown options, etc.).
   Example:

   Select the View all option in the Filters dropdown menu near the top-left of the page.

6. Denote usernames, passwords, CLI commands and output, and other similar text as code. Use code blocks for larger volumes of such text.

---

Terms and Conventions

1. Use click over "tap" or "press".

2. Use select over "choose".

3. Precede product names with Plixer.
   Example:

   Plixer Scrutinizer
   Plixer Replicator
   Plixer Beacon

4. Use articles with Plixer product names only when referring to individual instances or deployments of the product

---

Writing instructions

1. Use numbered lists for instructions or how-to guides.

2. Use sequencers only to connect two actions within a single step.
   Example:

   Enter admin as the username and replicator as the password, then click on the Next button.

3. Avoid going over the same individual steps covered by wizards and other in-product guides.
   Example:

   Follow the instructions in the setup wizard and click on the Next button after each step.

4. Keep each step and each set of instructions as short as possible.