Style Guide Draft - iomagine/Technical-Writing-Portfolio Wiki

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.