Tips to successfully build your open-source projects #4. Document your project
There is nothing worst than an undocumented project. People shouldn't have to guess how to use your project by spending time reading your code.
Writing documentation is usually considered boring, similar to writing tests. It does not even help that developers frequently argue about the usefulness of documentation in the codebase. Some say that your code should be self-explanatory and that if you need to comment it, something is wrong in your code structure.
Either way, it is definitely out of the question to open-source a project without proper documentation if your goal is adoption: if you expect people to open your source files and read your self-explanatory code, your project will not go very far.
General Documentation
This is the documentation that you manually write, containing all kinds of information: installation instructions, getting started, special considerations, examples, FAQ, … The possibilities are endless since you have full control over what goes in there.
For example, cpp_redis has a Wiki that I manually wrote containing installation & compilation information, detailed examples, and an introduction of the main parts of the library.
There are various ways to build your own documentation: some large libraries have their own website (Bootstrap, Django, Ruby on Rails, …), but Github Wikis or readthedocs are very good alternatives for smaller projects.
Generated Reference
This is the kind of documentation automatically generated by some tools like Doxygen, Pydoc, Javadoc, …
These tools can automatically read your code and generate some documentation for all of your functions and classes. The developer usually needs to write comments in a specific format before each function, such that the tool can get all the information it needs to generate the documentation.
For example, cpp_redis has some documentation generated with Doxygen.
General Documentation vs. Generated Reference
So, which way to go for your project? Should you manually write some documentation, or just automatically generate it and publish the result?
I believe both are needed. I know it means that a lot of documentation has to be written, and that writing documentation is not very pleasant, but hear me out.
A good way to understand what you should put in your documentation, and how you should structure it, is to take the same approach as what I described in my previous article, Tips to successfully build your open-source projects #3. Have a sexy README: put yourself in the shoes of the person who will need this documentation.
One important part when taking this approach is to consider that there will be different types of people reading your documentation: new users, existing users, and contributors. Each of these people will have different needs, and it is hard to cover them all with a single approach.
Documentation for new users
New users are discovering your project. They should have a rough understanding of what your project can do thanks to your README, but that's not much.
New users are mostly looking for two things:
- Getting Started: How to install your project? How to get it running? How to do some basic configuration? What are some good examples?
- Supported Features: What are all of the features that you support? What are the limits of your project? Are there some ways for the user to work around these limitations?
Your README probably introduced a few of these things, but the documentation will allow you to expand and get into as many details as needed: while a README should be concise and only cover the essentials, there is no such constraint for a good documentation.
New users need to be guided for a successful onboarding. Keep in mind that new users did not build anything meaningful with your project yet: they may not be very patient if they can't find what they are looking for or if they can't make it work quickly, especially if there are some alternatives out there. Any friction is a risk to lose a new user.
To successfully guide a new user, get him started, and give him a detailed overview of your project, general documentation is the best choice: you can better design the onboarding experience for your project.
A generated reference will not help in any way to guide new users, and only a few people will be motivated enough to onboard themselves from generated documentation: where should they even start?
Documentation for existing users
Existing users are the people who built something meaningful with your project: they are actively using it and it is now part of their source code for example.
These users are different from new users because they are already using your library: they do not need to be guided anymore. Instead, if they are paying a visit to your documentation, it's very likely because they are looking for something specific:
- Improving an existing integration: As mentioned above, existing users already integrated your project into theirs. Now, they might want to push their integration further based on their needs. For example, they might want to tune some specific settings for better performance. If they want to improve an existing integration, existing users are looking for a detailed reference to see exactly what are all the options available to them and the possible side effects.
- Integrating new features: Besides improving an existing integration, existing users might want to integrate completely new features from your project. In this case, they will mostly act as new users and explore a bit of what your project can do from the general documentation. That being said, existing users are more likely to jump to the full reference as well to integrate new features.
- Troubleshooting issues: Another major reason existing users might be visiting your documentation is that they are having an issue and they suspect it could come from your project. First, they will certainly check existing issues in case anyone else reported something similar. If nothing can be found there, they will check the general documentation for more technical specifications and common pitfalls. As a last resort, they may even open your code to troubleshoot their issue.
As you can see, these users may need different types of documentation. Generated reference is probably their main go-to (to improve an existing feature), but they may also need to read your general documentation (to integrate new features), or even your source code (to troubleshoot issues).
One major difference between new and existing users is patience. Existing users are much more likely to be patient. They already built something with your project: moving away from your project may be time-consuming and risky for them. It is also usually in their interest to avoid adding unknown dependencies: they will prefer finding a way to do more with your project, rather than using more external projects.
Documentation for contributors
Contributors are the people who want to fix or improve existing features of your project, or add new features to it.
Contributors will spend a large amount of time reading and possibly modifying your codebase.
General documentation and generated references are probably less important for them considering they will dive into your code directly. That being said, having a technical overview of your project in your general documentation can be useful as a starting point for a new contributor (a Getting Started for contributors).
What really matters to them is the documentation in your codebase. Once again, some will say that their code is well-written and self-explanatory. However, keep in mind that contributors do not have an understanding of your codebase as deep as yours, they may not be as experienced as you, and they are usually looking to make a change related to their needs as fast as possible. Spending hours reading your undocumented codebase is a waste of their time, and it may throw people off from contributing to your project.
Conclusion
There are different ways to document your projects: writing documentation in your codebase for your functions and classes, which can then be used to generate a reference, and writing a general documentation.
None of these approaches are better than the others. Instead, they are complementary and help to cover the different needs of different users:
- New users interacting with your project will find a general documentation guiding them to get started more helpful.
- Existing users are more experienced and will need to jump into more specifics of your project thanks to some technical specifications in your general documentation and generated reference.
- Contributors will be more efficient with the help of documentation within your codebase.
Writing documentation might not feel enjoyable. However, your users will be thankful for it, and it will significantly help the adoption of your project by making it stand out from other projects with weaker documentation!
Read all my tips to successfully build your open-source projects:
Originally published at https://cylix.github.io on September 9th, 2017.
