This page summarizes additional technical writing resources.
Editorial style guides
An editorial style guide defines an editorial group's guidelines for communication. For example, which of the following rules should your organization adopt for headings?
- Put headings in sentence case (capitalize only the first word of each heading)
- Put headings in title case (capitalize most of the words in each heading)
Don't waste time and energy arguing about these sorts of questions. Instead, just ask your organization to adopt a particular editorial style guide. An editorial style guide provides a set of answers to questions about writing choices. It doesn't matter that one editorial style guide advocates sentence case and another prefers title case. It only matters that your organization adopt a single editorial style guide.
Ah, but which editorial style guide? You may already be familiar with general purpose editorial style guides (such as the Chicago Manual of Style or the University of Oxford Style Guide). However, your engineering team should use an editorial style guide specialized in technical writing. We recommend choosing one of the following:
- The Google developer documentation style guide provides editorial guidelines for anyone writing developer documentation for Google-related projects.
- The Microsoft Writing Style Guide provides guidelines for anyone writing technical documentation.
Do not write your own editorial style guide. Creating and maintaining a "house" editorial style guide requires tremendous resources and causes tremendous conflict. That said, some organizations coin new terminology that doesn't appear in an existing editorial style guide. When that happens, the organization can do either of the following:
- Ask the maintainers of an editorial style guide to add the new terms.
- Create and maintain your own usage guide or style sheet that codifies spellings and word usages for your organization's specialized vocabulary.
Documentation as part of software engineering
The book Docs for Developers: An Engineer’s Field Guide to Technical Writing is a practical guide to creating, measuring, and maintaining docs using examples, templates, and principles that you can adapt to the needs of your organization. Written by experienced writers and developers from Google, The Linux Foundation, Stripe, LaunchDarkly, and Monzo,
The book Software Engineering at Google features a chapter devoted to documentation as part of the software engineering process.
Open-source documentation opportunities
Google's Season of Docs is a program to foster collaboration between open source projects and technical writers. This is a good opportunity for people working on open source projects to enhance their technical writing skills.
Season of Docs runs annually. To stay informed about the program, join the Season of Docs announcements mailing list.
Writing for GitLab
GitLab's Technical Writing Fundamentals course helps GitLab and community contributors write and edit documentation.