I find myself looking at many open-source projects in a given week because I love reading people’s code. Reading another person’s code is one of the best ways to learn new things about your favorite technology and I have not been disappointed in that area. I’ve also been prompted to question some of my logic, but occasionally, I catch myself swearing over a project’s documentation, and according to this survey performed in 2017, the numbers are pretty bad.
While some people omit documentation for their projects because they feel it’s not important, others include half-baked documentation without a demo whatsoever, leaving the reader overwhelmed. You want to provide enough information to the reader in the most detailed way possible, while still being concise. This might sound hard, but it’s worth it.
The essence of this guide is to provide you with actionable tips on how to write a well-structured, and rich in details documentation that will help people make the most of your, existing or new, pet open-source project.
Keep in mind that this guide is for people who want to fill out their pet project’s README.md file but do not know how to begin. It is not aimed at big projects, although what you will be doing won’t differ much.
How To Structure Your Project Documentation
One of the most overlooked aspects of documentation is its structure. It’s not enough to write about your project in gory details without structure because the required details, at that point, might be lost in useless information. The best way to do this is to split your documentation into separate sections and provide the details where needed.
You want to start with a “getting started guide” where you showcase your project’s power and slowly move towards the architectural design where you explain exactly how your project does what it does. Also, the API section comes in handy for projects that expose API so you want to include it.
Now, let’s go through each section and explain what they do.
Getting Started Guide
This section is where you walk users through your project by performing a task. A good way to do this is to start with a finished result and walk through how to achieve the result with a step-by-step guide. Each step should do one thing and build on top of the last step. Bonus point if you catch some errors the user might run into while setting up the project, it shows you battle-tested the project.
API Documentation
The API documentation is where you write in-depth about the APIs the project exposes. Projects with multiple components are good candidates for this. You want to go through each component and highlight what options they expect and the type of options they expect if that matters.
You can immediately follow through with the architectural design or the “In the production guide”. Keep in mind that the ultimate is goal is to not provide extraneous details. Keep everything as concise as possible.
Architectural Design
The architectural design section is where you write about how your project does what it does. Explain a design decision and why that makes sense for the projects. You can also go through the inspiration for that the said design decision, this helps familiarize the readers with your mental model of the project.
You can also go into what potential contributors should look out for in the project should they decide to contribute. The best place for this is the CONTRIBUTING.md file, but I find it very helpful to have information like this in the main documentation.
License
This is a very important part of a project’s documentation because it dictates how people will interact with the project. It’s advisable to choose the one you are comfortable with as some licenses require modified copies of your work to be also open-source. This might not be what you want.
Also, if your project uses another project, be sure to check out that project’s license because some licenses require you to use the same license as the project your project is built upon. Below is a list of some commonly used licenses.
- Apache License, Version 2.0
- GNU General Public License v3.0
- MIT License You can find details for these licenses here.
Make sure you choose the one that fits both you (the author) and your project well.
That’s pretty much it. If you have suggestions or questions, drop a comment below.
Top comments (0)