Web DevelopmentHow to Write a Good Documentation for Open-Source Library?

Introduction

Just a few years ago, developers often underestimated the importance of good documentation and did not strive to master the art of writing it. If you look at the products of the Stone Age (i.e., products from a decade ago), you will find among them many libraries that do not have good (or at least some) documentation. Except, perhaps, the most popular. The developers of these libraries believed that a few code examples would be enough for any beginner to understand the idea and be able to use their development skills in practice.

But, due to the rise of the open-source movement, when writing documentation, we have to focus more and more on the end-user. Corporations have realized that the presence in the open-source world helps to attract customers and new developers, i.e., it is a valuable asset. Open source projects create a reputation as a reliable and solid company. As a result, there was a request to write good, solid documentation.

Another reason why developers have accomplished the importance of documentation is the competition of libraries in ecosystems. Before the advent of the npm era, this problem was not so noticeable. For example, in Python, there is usually only one way to do anything without any other. In JavaScript, before the arrival of Node, there were also not a large number of libraries that would perform the same function in different ways. Try to remember some popular alternatives to jQuery!

And today we can choose our technological stack. Therefore, developers of libraries and frameworks make considerable efforts to make it as easy as possible for a potential user to study and use their products. JavaScript developers can choose between Angular, React, Vue, and other less popular frontend frameworks, as well as between Express, Koa, or Sails in the backend. And that's even if you don't count the millions of other libraries that occupy an intermediate position!

What does good documentation consist of?

The project documentation consists of many things. For example:

• README file

• Background information

• User's Guide

• Collection of recipes

• Blog posts

Each point serves its purposes, but their boundaries are sometimes blurred.

README

The README file is often the first opportunity for potential users to get acquainted with your product. It may contain information specific to different types of documentation (reference books, manuals, etc.), but the README file cannot be confused with anything else. This file helps you "sell" your open-source library. At the same time, do not forget that the README text should be concise and informative.

Start with what your library is designed for in general, what user problems it solves. Examples of common use cases can be given. A well-written first paragraph is a great start for any README file.

If your file is longer than one or one and a half pages, it would be a good idea to add content (a list of content).

List the dependent packages that the user will need to install, specify what knowledge he must have in order to use your product. Describe the installation steps. Show basic code examples, preferably real-use case code. Attach a link to more detailed documentation.

Finally, include in your README file information about the product license and a list of contributors. You can also add a paragraph on how to participate in the development of your library. This file is commonly named CONTRIBUTION. Remember that one of the pillars of open-source is respect for other people's time. If your potential contributors can quickly understand the work of your library, everyone will benefit from this.

Background information

Reference materials are perhaps the most technical part of your documentation. Its purpose is to list the entire list of functions of your library, their expected inputs, outputs, and side effects, as well as the purpose and implementation examples. The examples in the reference book should be as isolated and self-sufficient as possible.

Background information is often generated automatically. There are also many tools to simplify updating the directory and to make it easier to work with it. But we should not forget that reference materials completely generated by a computer can be difficult for users to perceive. You need to try to include at least one sentence "from yourself" in each point of reference information.

It will be easier for some developers to understand your library if they have the opportunity to understand how individual functions are implemented. Therefore, a direct link to the implementation of the function in the code of your library will be a good addition to the reference information (although not mandatory).

User's Guide

The guide (guide, tutorial) should guide the user through all the functions of your library. If we are talking about large, popular general-purpose frameworks, the manual may be the most voluminous part of the documentation.

Start the guide by describing the scope of the library and what prior knowledge the user should have. For example, if we are talking about a library that helps manage HTTP requests, it is logical to expect that the user should be at least a little familiar with the basic concepts related to this topic.

In the description of any topics, first cover the most basic ones, gradually moving to the more complex ones. A good starting point would be to describe the installation process for different systems.

When you write a manual, try to imagine that a group of people is sitting in front of you and you need to explain to them how your product works. Remember that in terms of explanations, it's better to overdo it than to leave some concepts undeciphered — this way you will show more respect for users.

If possible, supplement the text with images and diagrams, as well as code examples. The code in the documentation should be as complete as possible so that the user can simply copy parts of it. At the same time, it should be divided logically and supplemented with comments on the application of the functionality presented in the code.

Don't forget to test the code in the examples as well. If the user copies a piece of code, it should be working. I can't even convey how angry the user is when the code from the documentation doesn't work.

Collection of recipes

If we are talking about large general-purpose libraries, the recipe collection is a collection of ready-made, carefully verified solutions to common problems that users may encounter when using your library. Unlike the manual, where new concepts are explained on the basis of those explained earlier, in the recipe book, each solution should be self-sufficient. The application of the functions necessary to solve the problem can (and should) be explained in more detail in the recipe book than in the manual.

The recipe collection is not a mandatory part of the documentation for small and specialized libraries. It makes sense to add it only if the explanation of the concepts is more complex than is acceptable for the text of the manual. In this case, the collection of recipes can be considered as a collection of short tutorials on achieving the desired result.

Speaking about the differences between the user manual and the recipe book, one more aspect should be mentioned. The guide mainly focuses on your own library. And the recipe book may well contain links to other documentation, as well as a demonstration of integration with other libraries. In addition, you can even explain why you prefer some language functions over others. This helps the user to better understand not only your library but also the programming language as a whole.

Finally, you can include in the recipe collection examples of when not to use separate solutions. You can also show examples of incorrect code and antipatterns. Most importantly, do not forget to visually separate them from examples of good code and the correct use of solutions.

Blog posts

Strictly speaking, a blog post is not really documentation, but it will still be useful for users. Other parts of the documentation focus on how to use your library in appropriate cases, and a blog post may reveal why it might be needed at all.

A blog post should help you connect with users and tell them how your solution is better than others. You can write about the problem that inspired you to create the library, or specify other reasons for its creation.

Please note that despite the name of the section, it may not be a blog post in the literal sense. You can do all of the above on GitHub Gist and put the link in the README file.

Before publishing

Proofreading of documentation is mandatory. Reading documentation with grammatical and punctuation errors quickly tires. Consider giving your documentation to a native English speaker or someone who knows the language well. If this option is not available, give your contributors the opportunity to make pool requests for documentation and ask them about it separately in the README. There are also a large number of automated tools at your service, for example, Grammarly or Hemingway.

And as I have already said, again, before publishing, you should definitely check all the code examples — they must be working.

Conclusion

Nowadays, when development trends change so quickly, documentation is especially important. By helping users get to know your library and use it, you promote your product in the open-source world.

Insights about Quality Assurance and Testing in Software Development

Quality assurance is a cornerstone in developing mobile and web applications. At Mobile Reality, we emphasize the critical role of manual and automated testing to ensure the delivery of robust and reliable software. We've curated a selection of articles that delve into the best practices and importance of quality in software development:

• Quality importance in software development

If you're looking to enhance your QA processes or are interested in discussing the rigorous testing of mobile and web applications, please contact our quality assurance team. We’re dedicated to partnering with you to elevate the standard of your software products. If you have a passion for ensuring software excellence and are considering a career in QA, explore our career opportunities and join our team of experts in pursuing perfection in software development.