Starting an expanded version of the style guide currently found in the Plixer Documentation group's wiki section that incorporates new recommendations from myself and Rosh.

Guidelines in italics are additions that may require further discussion.

Plixer Product Documentation Style Guide

Table of Contents

1. Introduction
2. Headings
3. Style and Tone
4. Stylization
5. Terms and Conventions
6. Labels and Linking
7. Code and Commands
8. 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 or "please."
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.

Terms and Conventions

1. Follow American English spellings, grammar, and conventions when writing.

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

3. Use select over "choose".

4. Use "log in" to refer to the act of logging in action and "login" to refer to credentials.

5. Precede product names with Plixer.

   Example:

   Plixer Scrutinizer
   Plixer Replicator
   Plixer Beacon

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

7. Avoid repeated content. When necessary, use links to reference the same content in other sections of the documentation.

Labels and Linking

1. Add a unique label (.. _sectionLabel:) for each tab, section, and subsection and compile a list of all labels used
2. Labels for list-type (lists of commands, glossaries, etc.) content are optional

Code and Commands

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. Minimize the length of each step and each set of instructions.