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.
Accessible writing
The Google developer documentation style guide provides guidelines for
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
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-04-17 UTC."],[[["\u003cp\u003eThis page provides a curated list of resources for enhancing technical writing skills, covering aspects like style guides, inclusive language, and documentation best practices.\u003c/p\u003e\n"],["\u003cp\u003eIt emphasizes the importance of adopting established editorial style guides like Google's or Microsoft's for consistency and efficiency in technical documentation.\u003c/p\u003e\n"],["\u003cp\u003eThe resources also include insights into the value of documentation within software engineering, with recommendations for books and online communities.\u003c/p\u003e\n"],["\u003cp\u003eOpen-source contribution opportunities like Google's Season of Docs are highlighted to further encourage skill development in technical writing.\u003c/p\u003e\n"],["\u003cp\u003eIt directs GitLab contributors to the Technical Writing Fundamentals course for specific guidance on writing and editing documentation within the GitLab ecosystem.\u003c/p\u003e\n"]]],["Technical writing resources are valuable, as shown by reports from Google and Smartbear. Organizations should adopt a single technical editorial style guide, such as Google's or Microsoft's, instead of creating their own. If new terminology is needed, a usage guide or style sheet can be created. The Google guide emphasizes accessibility and inclusive language. Resources like \"Write the Docs\" and \"Docs for Developers\" are available. Google's Season of Docs encourages open-source collaboration and skill development in this area.\n"],null,["# Technical writing resources\n\n\u003cbr /\u003e\n\nThis page summarizes additional technical writing resources.\n\nThe value of documentation\n--------------------------\n\nSeveral research organizations have studied the value of technical\ndocumentation to technical organizations. For example:\n\n- [2021 Accelerate State of DevOps\n Report](https://www.devops-research.com/research.html#reports) from Google.\n\n\u003c!-- --\u003e\n\n- [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)\n\n- [API\n Documentation](https://smartbear.com/state-of-software-quality/api/documentation/)\n from smartbear.com.\n\nEditorial style guides\n----------------------\n\nAn **editorial style guide** defines an editorial group's guidelines for\ncommunication. That is, an editorial style guide provides a set of answers\nto questions about writing choices. For example, which of the following\nrules should your organization adopt for headings?\n\n- Put headings in sentence case (capitalize only the first word of each heading)\n- Put headings in title case (capitalize most of the words in each heading)\n\nThe correct answer is that you shouldn't waste time and energy arguing about\nheading styles. Instead, just get your organization to adopt a particular\neditorial style guide and abide by its recommendations.\nIt doesn't matter that one editorial style guide advocates sentence case and\nanother prefers title case. It only matters that your organization adopt a\nsingle editorial style guide.\n\nAh, but which editorial style guide?\nYou may already be familiar with general\npurpose editorial style guides (such as the [Chicago Manual of\nStyle](https://www.chicagomanualofstyle.org/home.html)\nor the [University of Oxford Style\nGuide](https://www.ox.ac.uk/sites/files/oxford/media_wysiwyg/University%20of%20Oxford%20Style%20Guide.pdf)).\nHowever, your engineering team should use an editorial style\nguide specialized in *technical* writing. We recommend choosing\none of the following:\n\n- The [Google developer documentation style\n guide](https://developers.google.com/style) provides editorial guidelines for anyone writing developer documentation for Google-related projects.\n- The [Microsoft Writing Style\n Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) provides guidelines for anyone writing technical documentation.\n\nDo not write your own editorial style guide. Creating and maintaining a \"house\"\neditorial style guide requires tremendous resources and causes tremendous\nconflict. That said, some organizations coin new terminology that doesn't\nappear in an existing editorial style guide. When that happens, the organization\ncan do either of the following:\n\n- Ask the maintainers of an editorial style guide to add the new terms.\n- Create and maintain your own **usage guide** or **style sheet** that codifies spellings and word usages for your organization's specialized vocabulary.\n\nAccessible writing\n------------------\n\nThe Google developer documentation style guide provides guidelines for\n[accessibility](https://developers.google.com/style/accessibility).\nThis page is not an exhaustive reference, but it does provide some general\nguidelines and examples that illustrate best practices for writing accessible\ndocumentation.\n\nGeneral technical writing resources\n-----------------------------------\n\n[Write the Docs](https://www.writethedocs.org)\nis a global community of people who care about documentation. It provides\nexcellent resources on many aspects of professional technical writing.\n\nDocumentation as part of software engineering\n---------------------------------------------\n\n- The book [Docs for Developers: An Engineer's Field Guide to Technical\n Writing](https://docsfordevelopers.com/)\n is a practical guide to creating, measuring, and maintaining docs\n using examples, templates, and principles that you can adapt to the needs of\n your organization. Written by experienced writers and developers from Google,\n The Linux Foundation, Stripe, LaunchDarkly, and Monzo.\n\n- The book [Software Engineering at Google](https://www.oreilly.com/library/view/software-engineering-at/9781492082781/)\n features a chapter devoted to documentation as part of the software\n engineering process.\n\nOpen-source documentation opportunities\n---------------------------------------\n\nGoogle's [Season of Docs](https://developers.google.com/season-of-docs/)\nis a program to foster collaboration between open source projects and\ntechnical writers. Season of Docs provides a good opportunity for people\nworking on open source projects to enhance their technical writing skills.\n\nSeason of Docs runs annually. To stay informed about the program,\njoin the [Season of Docs announcements mailing\nlist](https://groups.google.com/g/season-of-docs-announce).\n\nWriting for GitLab\n------------------\n\nGitLab's [Technical Writing Fundamentals\ncourse](https://about.gitlab.com/handbook/engineering/ux/technical-writing/fundamentals/)\nhelps GitLab and community contributors write and edit documentation."]]
