Managing People

This page is about how to split the work of creating documentation between people.

The most important observation is that novices are usually better at writing and editing documentation as well as writing templates. There are some reasons for that:

1. They are beginners and, therefore, are in the same situation as reader. They don't have to imagine what questions may a reader have -- they just have such questions.

2. New developers find different bugs than people who know the project.

Therefore, you should pair writers with new developers. Documentation should be edited by only beginners. Templates also should be written by novices.

Smart people are not the best writers because it's hard for them to follow "one topic per one sentence" rule since they are just... too smart.

Sometimes you need experts to write documentation. But they are usually very busy. If you want to motivate them, write a bad first draft (or ask newbies to do this) and give them such draft.

Testing Documentation

You need somebody who will read your documentation. Don't allow them to use any other resource like Google. If they need it, consider it as a bug in documentation.

Sometimes it's better to write documentation before implementing and testing and give the docs to the users and ask them what they would do next? This is similar to "readme driven development" -- writing readme before everything else.

Finding Editors

If you do not have any editors, ask OReilly for help and releasing your documentation as a book.

Other observations

People care more about documentation if they are accountable for it personally (bugs in documentation).