Technical writing resources

Stay organized with collections Save and categorize content based on your preferences.

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:

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:

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

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.