Sparking Joy in Docs
Discover how to enhance coding projects by writing thorough, well-structured documentation. Learn to craft efficient READMEs with installation guides, examples, licenses, badges, and visuals to help users and teammates understand and engage with your code effectively.
Write good docs
The highest impact way a developer can spark joy is in writing good docs. It is the first thing every new user and teammate reads, and it shows that you care about the project.
You don’t have to create a bells-and-whistles docs site for every little project. For most things, a really good README is more than enough. However, you can do a lot to “sweat the README.”
Get straight to the point
Place installation, examples, and API docs upfront and use a Table of Contents generator to make them easy to navigate. Keep them up to date and write example code with the understanding that developers will copy and paste while skimming over most of the explanations. Even where copy and paste are not possible, like when developer keys are concerned, you can show the expected form of the key for people to visually verify that they have the right one, e.g., API_TOKEN= #, e.g., MY_API_TOKEN_1234
Tip: In the Node.js ecosystem,
dotenv-safeis helpful for enforcing checks that environment variables are specified properly.
Add appropriate license
Licenses matter in open source. Some legal interpretations don’t allow developers to even ...