BriteCore documentation style guide

Table of Contents

Purpose

The BriteCore Documentation Style Guide provides writing, diction, grammar, punctation, formatting, and other guidelines to follow when creating documentation and other collateral or deliverables. The Documentation Team follows this guidance exclusively. While much of the guidance in here discusses the general foundations of clean, accurate writing and is universally applicable across teams and departments, some is specific to documentation. Other teams and departments should use best judgment and discretion regarding applying such rules to their own deliverables.

The guidelines in this style guide are mandatory for Documentation Team deliverables.

Goals

When we create content, we have several goals:

  • Empower. Help readers understand BriteCore by using concise, informative language.
  • Educate. Provide readers with the information they need to know, not just what we want to say. Give readers the specific information they’re seeking, along with opportunities to learn more like links to other documents.
  • Guide. Walk our readers through the steps to solve their problems.
  • Respect. Treat our readers with the respect they deserve and have come to expect from BriteCore. Remember, they’re coming to us for help, so be thorough and don’t make assumptions.

To achieve these goals, ensure your content meets our standards:

  • Targeted. Know your audience and what they need to know.
  • Concise. Understand what you’re writing about. Use consistent, easy-to-understand language.
  • Useful. Prepare yourself to write helpful content by asking yourself a few questions before you start writing:
    • Who is going to read this?
    • Why are they going to read it?
    • What do they need to know?
  • Friendly. Remember, our readers are human beings just like us. While readers want documentation to tell them what to do and how to do it, they don’t want to read content written by a robot for a robot. Ask yourself if you would want to read what you wrote. If not, you can guarantee our readers won’t want to read it, either.
  • Complete. Make sure your content is thorough, including all the required steps, notes, and links to additional information. Provide our readers with the answers and solutions they’re seeking.

Resources

The rules in this document come from several sources:

Table of Contents