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.
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.
- Create concise drafts that are easy for our target audiences to navigate and understand.
- Produce complete, accurate drafts. Editing review should not require a rewrite or extensive research of the material.
- Use consistent language, punctuation, and formatting per guidance within this style guide.
- Use easy-to-understand language.
- Do your due diligence:
- Research. Look in GitHub (PRs), test sites, and Google Drive for answers before asking questions.
- Ask questions. Provide context, including the research you performed.
- Proofread. Check for spelling, grammatical, and formatting errors.
- Check for accuracy. Ensure all information/steps are included.
Note: If you can’t complete a step or access part of the software, note why you couldn’t. Always provide the technical editor a link to the test site you used.
The rules in this document come from several sources:
- Technical Editor rulings
- Microsoft Style Guide
- Chicago Manual of Style
Important: All rulings defined in this style guide supersede all other sources. External sources are used as a framework and to determine new rulings.