How to make your team write more documentation

Well, “make” is a bit too generous a word, but let’s go with it. Technical (and pretty much every other type) documentation is that thing that every developer says is very important, but probably will never do enough of it. Of course — nobody likes writing documentation (“it’s clear as day, why write this stuff down? I’d better explain it personally”), even despite its clear advantages like knowledge transfer, faster onboarding, etc.

A very few, probably too few teams actually spend time on documentation process. And it’s hard to blame developer teams, especially if they have no technical writers to help them. Devs have to write a lot of actual code, and have very little time for documentation. So is there any solution to this?

Don’t demand

Telling your fellow coworkers to “write more documentation” won’t do any good. Probably won’t do any bad either — most likely it won’t have any effect whatsoever.

Do it

Write documentation. Yes, it’s that simple. Show people that writing documentation can be done, and can be done on a proper level. Devote some of your working time to writing documentation.

Tell people you’re doing it

Every time you create a piece of documentation — create a new help topic or write a new wiki article, you can let others know. But don’t overdo it — don’t shove the fact that you’ve written some documentation in people’s faces. Show your colleagues the new stuff you’ve written, ask them for feedback. After some time, they will see that you actually can write documentation and do your work, and see the importance of the documentation as well.

Ask others to write some

After you’ve established a good example of yourself, gently ask people to write documentation as well. Did developer 1 implemented a new feature? Ask them to explain how it works. In written form.

But don’t expect people to do it immediately. First few times you ask them they may not do anything. But that’s okay. Any time something new comes up, ask people to document it. Or even ask people about the stuff they’ve coded from time to time, like you’re forgetting bits here and there. It’s a “dirtier” approach, but it can hint them that it’s better to just write an article once than answer these questions all the time.

Point others towards the pieces you’ve written

If someone asks you about some feature and you have it documented — address their issue. But after that — point them towards the documentation. Say that you’ve written it on that feature, and all of the info can be found there in case they need it later or want a more detailed explanation.

With time, people will see that the time it takes to write a documentation is nothing compared to the time they will potentially “waste” explaining something to somebody again and again. ANd they will start writing documentation as well. But you have to start with yourself — be a role model!

Have a nice day!

Bradley Nice, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors