How to Write to Be Understood by Your Team

If you write the developer documentation, your job is not simply to type characters. It’s transmitting knowledge to others. And this aim requires some rules to follow. Along with team documentation tools that enable you to author your copy, your attitude is your tool. Write to be understood. And this is how to do it.

Keep It Simple

The simpler the language you use, the better. Sophisticated sentences don’t work in the documentation the way they do in literature. Instructions should be short and clear.

•       Two short sentences are better than one long.
•       Rare words don’t indicate you’re smart. They indicate you boast more than you care.
•       Leave no place for guesses.
•       Figures can show more than words. Use both.

After you write the body of a page, reread it and find the words you can remove. Then remove them.

Nothing Is Obvious

If you are a part of the team developing the product, you are quite aware of its features and functions, using it easily. You may expect your teammates to be even better at it. But still, when you write the documentation, nothing should be skipped as “obvious.” What seems obvious for you may require long explanations for someone else.

It has to be step-by-step, always. When you describe actions necessary to obtain some results (access a certain section, apply an effect or transformation, complete a file operation, and so on), you may feel like skipping some steps. Don’t. That’s what single-sourcing is for: you don’t have to rewrite or copy/paste repetitive instructions, but you should make sure they’re where they belong.

One Word, One Meaning

It’s considered a good thing to do on the Internet to use synonyms and avoid overusing the same words (to reduce the word frequency within a text). Maybe it’s so when your copy is even a bit literary, meant for education, entertainment, reading by regular customers.

But when it comes to internal documentation, you can simply ditch all concerns of what-will-Google-think-about-it. Your mates won’t google the document. So come on, use the same terms. Don’t make them guess whether screen and display are the same thing. By the way, it’s a great idea to keep the glossary – just in case some terms do need explanation or differentiation.

Puns Aren’t Always Fun

When you write for curious googlers, it’s a good idea to drop a catchphrase once or twice a paragraph. The more they enjoy your copy, the greater is the chance they return for more. Internal documentation is not a place for verbal exercises. It does not have to be entertaining; that’s not the mission. 

Know Your Reader

You may be unacquainted with those who’ll read your content later. But you know that they join the team, so they have certain competencies necessary to develop. So don’t be afraid to use professional terms without inserting links whenever you use them. Again, there’s a glossary for that.

If you have something to add about writing comprehensible documentation, you can do it in the comments. Or share the article on your Facebook, Twitter, etc., so your friends could read and discuss it too.