The primary rule of writing documentation is: Revise it, many times, on separate days. You need to keep coming back to it, reading it with a fresh mind that hasn't thought of what you wrote for at least half a day, preferably longer. What seemed perfectly clear yesterday will come across as ambiguous today. You keep revising until the changes get smaller and start to feel cosmetic.
Your job is to write concisely, using simple, unambiguous language that's quick to read and easy to digest. It's a skill that must be learned, practiced, and honed.
We got up to 600 pages for a spec one time. And we could only do that because our intern figured out a trick to keep the text editor from panicking on that much text (edit chapters, concatenate them only to produce the final doc).
We got a nasty architectural surprise one day because the same paragraph appeared, ver batim, more than 40 times (I think it may have been as many as 60) in different sections of the document.
But one of them was worded slightly different from the others in the middle of the paragraph, negating some assumptions we had made about the information architecture of the system. I was pretty upset by this. What a hostile way to write documentation! It felt like sabotage.
To stop this happening again I wanted us to move clauses like this high up in the document and instead of repeating them, using one sentence to refer to the common constraint elsewhere. Then the difference would have stuck out like a sore thumb, and might not have been accepted. Unfortunately they weren't biting. As a consequence, document review got a lot slower after that incident.
One of my bosses at a previous job was a shockingly open and pragmatic person. On several occasions he stated that something we were planning to do was a trick you only get to use once, and did we really want to spend that trick on this particular issue or save it for something more important. This documentation trick felt cheap and poorly spent.
> Revise it, many times, on separate days. You need to keep coming back to it, reading it with a fresh mind that hasn't thought of what you wrote for at least half a day, preferably longer.
Agree completely. Can you recommend any resources that emphasize this point and provide similar helpful documentation guidelines?
Another idea is to try on different personas: Put yourself into different roles, e.g. the person who just looks at the examples and skips wall of texts, the person who wants to read up on every nook and crany, the person who has no technical background etc.
The cool thing about text is, that it can be many things to many people and this is even more true with hyperlinks. Try to cover all bases at least a little bit and people will ignore the stuff they dislike and go after the stuff they like.
I don't know of any resources offhand, but the principles of technical writing are very similar to code writing. The biggest difference is that computers only need to be told once, whereas humans need a few (controlled) repetitions and some examples in order to digest something.
- Don't Repeat Yourself: Describe it in one place, and then refer to it elsewhere in the document.
- Componentize: Build up smaller concepts and then use those smaller concepts to build up bigger concepts, etc. Then you can continue to use simple language with the bigger concepts that are easily broken down because they in turn are described in full.
- Each part does one thing and does it well. Don't mix many different concepts in one description. Describe one thing well, and reference it elsewhere.
- Keep things short. The longer a section is, the harder it is to absorb.
- Naming is important. Use memorable, descriptive names for your concepts.
- Have examples that demonstrate your concepts. Don't try to pack many concepts into a single example; that just makes it harder to figure out.
- Have a glossary if there are more than 10 new concepts.
- Test your documentation on people who are unfamiliar with the project. Ask them where they're getting confused. Confusion is the human manifestation of a bug in your documentation.
- Always keep your goal in mind. What should the end result be with your reader? Anything taking longer than 10 minutes is a chore, and only the most dedicated would continue that far.
- U/X is important. UI layouts, source code, and documentation all have U/X components to them because a human will be interacting with them / consuming them in some form. Make it easy for them to navigate to what they need.
Your job is to write concisely, using simple, unambiguous language that's quick to read and easy to digest. It's a skill that must be learned, practiced, and honed.
It's also a good idea to explicitly spell out the meanings of "must not" etc, because people (especially non-native speakers) sometimes get confused. Example: https://github.com/kstenerud/concise-encoding/blob/master/cb...
It doesn't take up much room, but it saves a whole lot of trouble down the line.