Personal tools
How to write a good documentation - The big Plan

A room without books is like a body without a soul (Cicero)

May 30, 2014

How to write a good documentation - The big Plan

Earlier this year I had a perfect chance to participate to a sprint where the organization of documentation was the main purpose. Here it is what I learned

From ideas to reality

As you may know, what leads an open source project to the glory it's a well-written, clear and accessible documentation. This is more and more true as we are leaving the first era of internet where the technology was the king and we are entering the era where technology is just a tool that provides features and everything is more black boxed.

The target audience(s)

The main thing to keep in mind when you write a documentation is: what's the audience that you are targeting?

This is very important because you may be too technical for non-techies and too naive for techys.
For the sake of the discussion, let's say that you have more than one target audience, for example end users and developers. You have 2 choices:

  1. to keep everything in a single place
  2. "divide et impera", so to have separate documentation for each target.

This choice is very personal and depends also on the amount of information that you have to deliver, the manpower that you have available and how you plan to maintain and update your documentation. For example, if you have few manpower you may decide to keep everything in a single place to make it simpler to maintain it. Be aware though that this case is the more tricky 'cause you have to make clear what's the target audience of every part chapter, or even sentence. This is also linked to the usability of your documentation. Always try to think by a different perspective. Lets say that you are an end user and you arrive to your documentation, you would be lost if were led to think that this was an easy documentation and instead you see very technical terms.


Once you have decided either to keep everything in one place or the divide it, you have to plan a good index since it's very important to have a flow of information and not a bunch of ideas without any link between them. For example, if you are targeting end users, you will want to start from a bird's-eye view in the first paragraphs and then to go more into details. In this case the first paragraph may need to be very generic and try to give a big picture of "what is this project about?". On the other hand, developers tend to be very impatient and pragmatic. Normally if your target audience are developers, you may assume that they already know what's your project about and so you can spend few words on the beginning for describing it. Instead you may want to start with putting on the plate the best parts of your project and why in the hell they should choose your project instead of thousands other similar ones.

The information flow and the index

And so you decided to write a good documentation for our shiny project, right? Excellent... now what?!

Well, if you were like me that I hardly could write 2 pages of essay, you will a method. This is even more true if you are not on your own and you have a team of writers.
But first things first! In order to plan a good documentation, you need 3 things:

  • a good index
  • a good information flow
  • a good plan for maintenance.

In the old days, the method that they taught me was to put down all the ideas like in a brainstorm and then organize them. Well, it turned out that this is still applicable for writing good documentation.
As a start, you can put all your ideas on post-its and put them on a wall. Then you can take a step back and have a big picture of what you have and what you miss.

Warning: The post-it and wall method would need good eyes and, depending on the amount of information, more than one wall

Once you have all the ideas on the wall, you can start to group them together based on the similarity. You may start to see groups of post-its that can be merged or split. You may also start to see "labels" for the groups. Well, if you continue on this path you will easily end up with a mind map. And this was the purpose from the beginning: you totally need a mind map!

A mind map will help you with keeping the big picture always in front of you and if you follow it, you also have your index for the documentation. You need to spend much time on this point 'cause it's crucial to have a good index that will lead your target audience on the path that you decided for them.

As soon as you have a good index, you will find out that filling the gaps with actual information is much much more easy. Just keep in mind to preserve the flow of information. In the best of the possible universes, one should to be able to print your documentation and read it like a book and even enjoy it.

From theory to practice

Once you have planned your documentation, you will want to start to write it. Then you need a good tool especially made for documentation. One of the best tools out there is Sphinx. Sphinx is very well known in the Python community 'cause it was originally created to write down the Python's (the language) documentation.


Sphinx is a tool that makes it easy to create intelligent and beautiful documentation

Sphinx has many good features that you will absolutely need:

  • once your wrote your documentation in reStructuredText, you can have it converted in almost every possible format like pdf, latex, html, epub and much more. This is perfect for the approachability of your documentation!
  • Sphinx has beautiful themes and it's quite easy to write new ones
  • your documentation can be hosted for free on readthedocs.org
  • it can be easily translated by using Transifex modules that will cut down your documentation in gettext strings, push them to transifex and pull them back. Once Sphinx have translated strings, it will use them
  • thanks to Asko Soukka, it even possible to have auto-generated screenshots of your project (supposing that it's a web based project) with the integration of robot framework into Sphinx.

Conclusions

In the end, to write a good documentation, everything you need is a big good plan. You need to plan a good index, you need to plan its maintainability and accessibility.

This blog post didn't wanted to be a complete essay on how to write a perfect documentation but just a good starting point. I would invite you to read even more on this topic. If I may, I would suggest to start with these sources:

comments powered by Disqus