Writing Good Documentation for Your Open-Source Library

Just a few years ago, developers often underestimated the art of writing docs and the value of having good documentation. If you look into the stone age (read: ten years ago), you will find that many libraries, perhaps aside from the most used ones, lacked good, or even any, documentation. Developers often expected that a few code examples would be enough for a newcomer to grasp what they’d had in mind and how to use their work.

The growth of open-source, though, demanded that documentation be written more and more with the end-user in mind. Corporations realized that presence in the open-source world is a valuable asset for attracting new clients and new developers. Open-source projects build credibility and establish reputation. Thus, the incentive to write solid docs became more and more important.

Another reason that I’d attribute primarily to the growth of Node as a popular technology, is competing libraries within ecosystems — a situation rarely seen before the advent of npm. In Python, for instance, there usually is one way to do one thing. In JavaScript, before Node, there also weren’t many libraries to do one thing in different ways — just think about any popular alternatives to jQuery.

Nowadays, though, we can pick and choose our technology stack, and developers of these libraries and frameworks put in extensive effort to make learning and using them as painless and quick as possible. JavaScript developers can choose between Angular, React, Vue and many other, less popular frameworks on the front end and Express, Koa or Sails on the back-end, in addition to a million other libraries in between.

Components of a good documentation

There are many parts to a documentation, among others:

• Readme
• Reference
• Guide
• Cookbook
• Blog post

Each of these fulfills different purposes, and the boundary between kinds of docs is sometimes blurred.

Readme

The readme file is often times the first contact potential users make with your product. It can be thought of as a bit of a combination of each other type of docs, but is in some ways unlike any of them. Readme is how you sell your open-source library. Note, though, that you should be brief and informative.

Begin by describing what your library helps your users with and what problems of theirs it solves. You can try giving examples of common use cases. A well-written opening paragraph is a great start to any readme. If your readme is longer than one and a half pages, a good practice is to include a table of contents. 

List prerequisites and dependencies that the user should have and describe the installation process. Show a basic example of code, even better if it’s a real use case, and link to a more detailed documentation.

Finally, include a license and list contributors. You can also include a paragraph on how to contribute to your library. Remember, open-source is based on respect for each other’s time, and if your potential contributors can get up to speed on how to get your library running, everyone is a winner.

Reference

A reference is perhaps the most technical document of your documentation. Its purpose is to list all functions your library exposes; their expected inputs, outputs and side effects; purpose and implementation examples. Examples in the reference should be as isolated and self-contained as possible.

A reference is often times generated automatically, and there are multiple solutions to simplify working with it and updating it, however, you should remember that a reference that is exclusively computer-generated may be difficult to understand for your users. You should make an effort to include at least a sentence of your own written explanation per item in the reference.

Also, certain developers may find it helpful to understand specifically how a particular function is implemented. A nice-to-have feature, although certainly not a must, is a direct link to the function implementation in your library’s code.

Guide

A guide is, in essence, a tutorial helping your user navigate through all the features of your library. In the case of large, general-purpose, opinionated frameworks, the guide may be the largest document of the documentation.

Begin your guide by outlining its scope and establishing what prior knowledge the user is expected to have. For example, if you’re writing a library that helps with managing HTTP requests, the user would be expected to at least be slightly familiar with the basic concepts of the subject.

Start at the beginning – cover the most basic topics first, and gradually move towards more complicated ones. A good starting point is always the installation processes for different systems. It may be useful to imagine a group of people sitting in front of you who you want to explain your product to. Remember that in this case, it is more respectful to your users to over-explain than leave important concepts unclear.

Include pictures and diagrams where relevant, as well as code examples. You may want to make the code in your documentation as complete as possible to allow the user to simply copy-paste certain parts, but it should be logically split and interspersed with comments and remarks on general applications of features exemplified in the code.

Remember to also test your guide. If the user copy-pastes every code example in the guide, it has to work. I can’t stress enough how frustrating it is for the user to have code examples from the docs not work.

Cookbook

In the case of large, general-purpose libraries, the cookbook is a collection of in-depth solutions for common problems your users may face while using your library. Unlike the guide, which builds on earlier concepts, each recipe in the cookbook should be self-contained. Also, applications of features necessary to solve a problem can and should be explained in more detail than in the guide.

Cookbooks aren’t necessary in cases of small and focused libraries, and should be considered only when discussing concepts that require greater complexity than you could reasonably put into the guide. As such, the cookbook can be considered a collection of short tutorials on how to accomplish a desired result.

Additionally, while the guide should focus primarily on your own library, in the cookbook recipes linking to other docs and showing integration with other libraries are encouraged. Further, you can explain why you use some language features over others. That helps your user not only become more proficient at using your library, but also the programming language in general.

Finally, you can include examples of when not to use certain solutions or show off incorrect code examples or anti-patterns. However, remember to visibly distinguish them from the correct examples.

Blog post

A blog post, while perhaps not strictly a part of the documentation, is still an important piece of information that your users can appreciate. While the other parts of the documentation focus on how to apply your library to relevant use cases, your blog post should explain why that was needed in the first place.

The point of a blog post is to connect with your users and tell them why your solution is better than others. You can write about the problem which inspired you to write the library or show the reasons for its existence.

Note that despite the name, you don’t need a blog to write a blog post: you can do it in a GitHub Gist and link to it in the readme.

Before publishing

Proofreading documentation is important — reading docs with poor grammar and punctuation quickly becomes tiring. Consider giving your docs to a native speaker or someone experienced with English who can help you with the language. If you don’t have that option, let your contributors send pull requests to your docs and even specifically request that in the readme. There are a number of automated tools at your disposal to help with this as well, such as Grammarly or Hemingway.

I will also reiterate that before you publish your docs, verify that all your code examples are working.

Conclusion

In the current era of constantly changing trends in development, documentation is more important than ever. Allowing your users to get up to speed on using your library and assisting them in learning it can be an important factor in establishing your project’s presence in the open-source world.

And besides, writing docs isn’t so bad!