This is a glimpse of Art of Open Source Documentation
Documentation helps your users succeed with your software, empowers them to be self-sufficient, enables them to give further feedback, and is the organizational backbone of your project.
There’re three elements of a good documentation
WHAT problem your project solves
If people don’t know why your project exists, they won’t use it.
WHY your project values
If your project cannot offer special and unique value, people won’t use it.
HOW to use your project
If people can’t figure out how to use your code, they won’t use it.
There’re several rules for the three elements above,
State the goal of your code;
Use a lot of hyperlinks to provide more information – this is a great way to keep your docs clean and to define jargony and niche terms;
Provide a Table of Content to help contributors organize their work. The open source maintainer acts as a sort of curator, who not only invites everyone to participate, but makes sure there’s a sense of order, common voice, and good user experience;
Use a tool to track revision history to help your users understand what has been updated;
Since you may not have a tech writer dedicated to your project, it also makes sense to use description tools that allow you to automate a lot of the doc writing. This leaves room for your community to annotate with that personal touch;
Create a CONTRIBUTING file to communicate with your users how best to collaborate.
Finally(and important in my mind), while the main purpose of the open source world is not profitability, you should look through your docs for potential to monetize. As you annotate your code and docs, always keep an eye out for pathways for upsells and better marketing. And while docs aren’t blogs, that doesn’t mean you can’t add social media share buttons to create more virality around your open source project.
