Writing Effective Documentation for Your Open Source Projects

I am just beginning to write documentation for my open source projects. I have had some stumbles along the way but I am still learning how to communicate what each app/tool does.

Here are some of the basics that I am learning while drafting my docs:

  1. Have a good Description and Getting Started sections to get a user up to speed on installing the tool/s on their local machine for testing and development.

  2. Make sure you outline the dependencies for the project. Do you need to install node or another tool? Let the user know in the Dependencies section.

  3. Make sure you break your Installation section down to be as clear as possible. Be concise; let the user know how to install the tool/s step by step. Brevity where it needs to be and more elaboration if something is complicated.

  4. If it is a large open source project, having a Testing section should be something you consider. Let the user know what test suite you are using and how to run the tests.

  5. And finally, add a Deployment section to help your user get up in running in a production environment.

Styles and Themes

If you want a singular place for your documentation, blog about the project, and other materials, think about using a theme and hosting it on a service like Now, Netlify,or Surge.sh.

Picking a static site generator is the hardest part. There are a lot to choose from however whatever you choose should make getting markdown in and out of it relatively easy and the build time should be fast. I am using Docusaurus by Facebook.

I have my docs set up on Netlify and you can find them here and here.

Interesting Tweets This Week

Wrapping This Up

It’s been a good couple of weeks here in Central PA, at least for me. Will have more news as it comes.

P.S. If you like what I am doing here, be sure to subscribe, follow me on Twitter, buy me a coffee, a book, or support me on Buy Me a Coffee and share the love. You can also subscribe to this newsletter’s rss feed or you can ask me anything.

👋🏾 Hi. I’m Tiffany White. I am a front-end engineer and egghead.io instructor. I sometimes contribute to open source, and blog about web development at Tiffany R. White Blog. I love JavaScript, React ⚛️, and herding cats 🐾 🐈