Make your open source project documentation suck less
I just stumbled into this talk about documentation by Jacob-Kaplan Moss and it was really an insightful look into how one must design the documentation for an open source project. Below is the gist of his talk:
Documentation is communication
This is the single most important point that you need to understand. Documentation is not just written as a guide, but as a means to communicate with various developers and users across the globe. And if you think about it, your project is close to worthless, if you cannot communicate effectively about it to your users.
Documentation also makes your project accessible to all category of users, ranging from complete newbies to experienced users and internal developers. And thus, documentation should be written keeping all this in mind.
So then comes the main question “What to document ?”
What to document?
Tutorials
Tutorials provide the icing layer on top of the cake. A cake with a creamy top is much more attractive and mouth-watering than a plain cake with no cream at all.
In the same way, tutorials help your users to get a good feel about your project. They can get to know how easy or hard it is for them to use it, and also get a gist of how things work. So write tutorials to make users feel comfortable with your project. They’re a lifesaver.
Topic Guides
There are two types of topic guides that you may be interested in writing:
- Conceptual:
- Comprehensive:
Reference
This section generally contains some advanced documentation like the API specification, which are targeted for experienced users. It can also contain some links that help in gathering deeper knowledge about topics related to your project.
As much as possible, try not to auto-generate the documentation for this section, because nothing in the end is more awesome that documentation written and organised by people.
Troubleshooting
This section should contain questions that pertain to the pain points in your project and how to deal with them. Make sure that Q’s you mention in this section are actually FA’d.
Awesome ! So, now you may go write some kick-ass documentation !
You can watch the complete talk here.