Sparking Joy in Docs

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-safe is helpful for enforcing checks that environment variables are specified properly. ...