This page summarizes additional technical writing resources.
The value of documentation
Several research organizations have studied the value of technical documentation to technical organizations. For example:
- 2021 Accelerate State of DevOps Report from Google.
2022 State of DevOps Report data deep dive: Documentation is like sunshine
API Documentation from smartbear.com.
Editorial style guides
An editorial style guide defines an editorial group's guidelines for communication. That is, an editorial style guide provides a set of answers to questions about writing choices. 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)
The correct answer is that you shouldn't waste time and energy arguing about heading styles. Instead, just get your organization to adopt a particular editorial style guide and abide by its recommendations. 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.
Inclusive and accessible writing
Some editorial style guides aim to help you write documentation with accessibility and inclusivity in mind. The Google developer documentation style guide provides guidelines for accessibility and inclusive language. These pages are not exhaustive references, but provide some general guidelines and examples that illustrate best practices for writing accessible and inclusive documentation.
General technical writing resources
Write the Docs is a global community of people who care about documentation. It provides excellent resources on many aspects of professional technical writing.
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. Season of Docs provides 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.