Summary

Document your project

There is nothing worst than an open-source project with no documentation. Don’t expect people to open your code to understand how to use your project or discover functions: no one wants to do that.

There are two main ways to provide documentation: a wiki on Github and automatically generated documentation.

Until now, I always preferred the wiki way because you can guide the user and only show him what you want. I’ve always found that automatically generated documentation is big, confusing and lots of information are unnecessary.

But I now believe that is one of my mistakes: wiki is not enough and unmaintainable especially when you project tend to be bigger.

This is 100% NOT maintainable!


Instead you should mix both ways:

  • Use the wiki to guide the user: how to install the library? How to use it? What are some detailed example? What are some important details to understand? What are the core features and functions of your project?

  • Use the automatically generated documentation to allow people to find fine-grained information and discover your API and provide documentation for all released version of your project. It also force you to write functions and classes related documentation in your source files, making it easier to contribute to your project.

From my experience as a contributor, wiki alone is not maintainable for the project contributors and hard to version (for example, older versions of my projects are undocumented…).

From my experience as a developer, generated documentation alone is pointless. It does not help anyone to understand how to make it work and only force you to spend hours going through the documentation to find by myself what I was looking for.

That’s why considering using both for your project sounds reasonable.

Of course, don’t forget to keep both your wiki and your generated documentation up-to-date.