Uncluttered Documentation – Remove the Caveats

Sometimes it seems like documentation authors believe they are getting paid by the word. You should focus on writing as little documentation as possible. With every word you add to you documentation you decrease the likelihood that someone will read it. Repeat this over and over to yourself as you write your documentation and the quality of your output will improve dramatically.

We personally believe that, in many cases, it is better to have less detailed documentation that is not technically “complete”. What do we mean by that? There may be something you are documenting that has one caveat that affects 1% of your users, another that affects 2%, etc. If you put all of those caveats in your documentation you create a cluttered mess.

You have therefore made you documentation useless for everyone.

What is the point in that? Write your documentation for 90% of your user base. Then create a separate section for those niche cases, a section that the 90% never need to see.

The next time you are writing a lesson or tutorial, try this technique. Pull out all of the caveats. Focus on making the documentation clear for the majority of your users. Your documentation will be easier to write and easier to read and will actually become useful.