By Robert Delwood, a Lead API Documentation Writer
We all know that style guides are important to writing teams. They define the grammar, voice, style, and ensure consistency among the documents. There’s no lack of styles guides out there to pick from, either. To save time, teams often pick an existing standard such as Google, Chicago, or APA (American Psychological Association).
However, many groups deliberate too long selecting a style guide. They’re are all good choices and you can’t go wrong with any of them. Instead, concentrate on your team’s writing preferences or differences. For example, your team may prefer a lower case am/pm time notation rather than Chicago’s capital AM/PM. The selected style guide may not even address some issues, such as how API documentation is styled. In both cases, it’s perfectly acceptable to deviate from, supplement, or create new entries for, your selected style guide. If you do this, you create your own style guide. In fact, it’s common to have more than one style guide. These include for copy writing, technical writing, API documentation writing, and marketing. Each one is its own specialty, audience, and nuances. Therefore, it’s reasonable they can each have their style guide.
Multiple style guides can be listed in a hierarchical fashion. For instance, the company’s branding guide may be the ultimate reference. This would be for brand names or styles protecting their copyrights, trademarks, or other proprietary information. The department style guides come next. Finally, the Chicago guide would be used for all other cases. Of course, enforcing the style guides is another discussion altogether.