How to build a documentation culture

Some of you probably don’t like writing documentation, most of you might even hate it. Writing docs often seems to be treated like the annoying but necessary task that is left until the last minute or sometimes forgotten about altogether. However, writing documentation is important for a number of reasons:

• Not writing good documentation creates technical debt.

• If you have poor docs, your colleagues (new team members in particular) or your end users have to ask you questions — this costs you time!

• Without docs, you create knowledge silos where only a few engineers know how an aspect of your technology works. If these people leave your team it creates knowledge gaps.

If you think documentation is lacking at your company, whether it is a tech startup or a mature software company, there are a number of things you can do to try and build a better documentation culture.

1. Find someone to drive it

If you don’t already have a technical writer, UX writer or content specialist in your team and you have the budget, then hire one! They will become the foundation of establishing your docs culture.

Alternatively, you could try finding a “documentarian” — or “friend of the docs” — a programmer or perhaps a tester who is a good wordsmith and knows enough about your existing documentation and is willing to help drive the documentation effort.

2. Create a style guide

You can establish a form of quality control by picking or writing a style guide. This becomes your reference to ensure best practices and for things like terminology, capitalisation, syntax and tone and voice. If you don’t have the time or resources to write your own, you can adopt an existing one. Most technical writers refer to one of the following:

• Microsoft Writing Style Guide (formerly Microsoft Manual of Style)
• Chicago Manual of Style
• Google Developer Documentation Style Guide.

You will also find some useful style resources at Write the Docs, a global community of people who care about documentation. There is even an entire page about style guides!

3. Use spell checkers and linters

Another way to establish consistency in your technical content is to encourage the use of spell checkers and linters. If you use open-source text editors like Atom or Sublime, you can install free spelling checking linters to help drive the accuracy and consistency of spelling and grammar. Some linters and tools you could consider include:

• Alex: Linter available on multiple platforms.
• American linter: Linter to make spelling American again. This is useful if you're from Europe, Asia or Africa but work for a US-based company who use American spelling.
• Hemingway: App that checks content for passive voice and gives a readability grade level (a high grade level means your text may be confusing or tedious for the reader).
• Write Good: Linter for English prose for developers. Available for Atom and Visual Studio.
• Vale: A natural language linter that supports plain text, markup and source code comments. Available via CLI and as a desktop app.

Alternatively, you can create some form of presubmit check or filter to prevent specific typos or spelling mistakes. It may be little heavy-handed but I have created several presubmit checks to prevent developers in my current team from using ambiguous terminology.

4. Raise bugs

Another good way to raise awareness about documentation is to raise bugs against spelling or grammatical issues in your product itself or in the codebase.

When I joined a startup, I was initially nervous about raising bugs and interrupting developer velocity but after a few months of highlighting things like spelling issues, passive voice and typos, more and more engineers started coming to me for advice about content such as error messages, release notes, parameter names and code comments so we were able to ensure the text was correct in the first place.

5. Reward writing

While it might sound cynical, offering your colleagues rewards or incentives for contributing to the documentation can work. Some things you might consider include:

• Running a "doc-a-thon" or one-day docs sprint and offering prizes to the people who contribute the most documentation changes.
• If your company runs a peer bonus scheme like Bonusly, give contributors peer bonus points for their documentation efforts.
• Offer physical rewards or swag for contributions to docs such as stickers or mugs.

As a naive junior technical writer, I even had some success with buying chocolate bars for developers who helped me with documentation but I’m not sure this is the healthiest option for your colleagues or your wallet!

6. Offer documentation training

If you’re a solo documentation writer in a large team of developers, you can’t realistically be expected to write everything. Your best bet is to teach your team some documentation best practices to improve the quality of your docs. Some topics you might want to cover include:

• Voice: Using active voice instead of passive voice. The latter can create ambiguity.
• Ambiguity: Avoiding the use of words that can create ambiguity. For example, if an action is mandatory use ‘you must do x’ instead of ‘you should do x’. The word 'should' suggests an action is optional.
• Audience: Encourage your team to think about who they are writing for and any prerequisite knowledge or tools they might need.

7. Give talks about documentation

I used to be terrified of public speaking but over the past two years, I’ve given a number of internal and external talks about documentation and best practices.

It’s not only been a great way to test yourself and overcome your fears (if you’re not a comfortable public speaker) but it also helped to raise awareness about the importance of technical documentation both at your company and in the wider community.

8. Use the open source community

If your product is open source, you can reach out to technical writers and documentarians in the open source community to help with your documentation.

Some companies like Google run open source initiatives where they actually pay technical writers to contribute to open source projects. See Season of Docs for more details.

Summary

So in summary, if you want to get started and build some form of documentation culture and improve your company’s technical content:

• Find a writer or “documentarian” to drive the docs.
• Create or choose a style guide to establish consistency.
• Use spell checkers or linters to establish quality.
• Raise bugs to raise documentation awareness.
• Reward writing to encourage others to contribute.
• Offer training to empower your colleagues.
• Give talks to inspire and teach others about docs.
• Use open source if you need more help!

There are probably lots of other things you can try but if you attempt some of these suggestions, I think you’ll be on your way to creating a documentation culture at your company. Good luck!