Kushal Das

FOSS and life. Kushal Das talks here.


Document you code: part1

documentation == communication

Yes, it is the primary medium to communicate to you users. You may have an API service or an installable library or an application, but your documentation quality matters when you think about retaining old users and getting new one!


Above is an old sketchnote I did, happiness of the users matters most and it can only come with providing a superb documentation along with your application/API.

Documentation comes in different forms, for the users first thing is a quickstart docs, something which can tried within 5-10 minutes, then comes tutorials and how-to guides, which can vary from 30 minutes to couple of hours to complete. API documentation comes after that, mostly for your experienced users, in-depth details and examples should be part of it.

There are many projects who will not accept a patch without the necessary documentation changes along with it. If you look into projects like Django or Qt , you will understand why they have such big userbase. Along with the excellent product, they provided world class documentation. There is another point which these projects teach, who should write the initial documentation?

Developers should write the initial documentation!

You read correct, not any new contributors but the developers themselves. As a developer, you already have better idea of the project and how it works, if you write the initial documentation that will help more for new contributors than them trying to find out how things work and then write the docs.

In next part I will discuss more on code comments.