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](https://www.devops-research.com/research.html#reports) from Google. - [2022 State of DevOps Report data deep dive: Documentation is like sunshine](https://cloud.google.com/blog/products/devops-sre/deep-dive-into-2022-state-of-devops-report-on-documentation) - [API Documentation](https://smartbear.com/state-of-software-quality/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](https://www.chicagomanualofstyle.org/home.html) or the [University of Oxford Style Guide](https://www.ox.ac.uk/public-affairs/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](https://developers.google.com/style) provides editorial guidelines for anyone writing developer documentation for Google-related projects. - The [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) 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. ## Accessible writing The Google developer documentation style guide provides guidelines for [accessibility](https://developers.google.com/style/accessibility). This page is not an exhaustive reference, but it does provide some general guidelines and examples that illustrate best practices for writing accessible documentation. ## General technical writing resources [Write the Docs](https://www.writethedocs.org) 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](https://docsfordevelopers.com/) 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](https://www.oreilly.com/library/view/software-engineering-at/9781492082781/) features a chapter devoted to documentation as part of the software engineering process. ## Open-source documentation opportunities Google's [Season of Docs](https://developers.google.com/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](https://groups.google.com/g/season-of-docs-announce). ## Writing for GitLab GitLab's [Technical Writing Fundamentals course](https://university.gitlab.com/courses/gitlab-technical-writing-fundamentals) helps GitLab and community contributors write and edit documentation.