Introduction
Just a few years ago, developers often underestimated the importance of software documentation and didn’t prioritize writing it well. If you look at open-source projects and its open source software documentation from a decade ago, many libraries lacked proper technical documentation—except perhaps the most popular ones. Developers believed a few code examples were enough for beginners. However, with the rise of the open-source movement, the need for clear open source documentation has grown. Companies now see contributing to open source as a way to build reputation and attract developers. Solid open source software documentation is a valuable asset. Increased competition in ecosystems has also driven the demand for better docs. Before the npm era, this issue was less noticeable. In Python, there was typically one way to accomplish tasks. In JavaScript, before Node, few libraries offered alternatives to tools like jQuery. Today, developers can choose between frameworks like Angular, React, Vue, or backend options like Express and Koa. To stand out, library creators invest in software documentation tools like GitBook that offer collaboration features. These documentation tools make it easier for users to study and adopt new technologies.
What does good documentation for open source 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 in eq. Confluence or Github
The README file is often the first chance for potential users to engage with your product. It serves as a gateway to various types of documentation like internal documentation, API documentation, or product documentation. Your README should clearly outline what the library does and what problems it solves. Include real-use cases and concise great documentation. For longer READMEs, add a table of contents to improve navigation. List dependencies, installation steps, and required knowledge. Integrate version control details and link to platforms like GitHub Pages or Confluence for detailed docs. Mention any documentation process or source tools like BookStack or Docusaurus. Highlight community contributions, and outline how others can participate in the development process. A markup language makes formatting easier, while a clear license and contributor list complete the README. Effective open-source documentation saves time and boosts adoption for everyone involved.
Background information in docs
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 for the software documentation
A guide should walk users through your library's functions and is often the most detailed part of software documentation for large frameworks. Begin by outlining the library's scope and any prior knowledge needed. For instance, if it's for handling HTTP requests, users should understand basic networking. Structure the guide to introduce simple concepts before advancing to complex ones. Detail the installation process for different systems. Use clear technical writing principles to ensure clarity. Think of explaining the library as if you were presenting to a group. Supplement explanations with diagrams, images, and tested code examples. Well-organized, commented code helps users understand functionality better. Ensure code examples are fully functional to avoid frustration. Technical writers often use tools like Sphinx Docs to produce clear, structured content. Include release notes for updates and improvements. A thorough guide enhances the software development process and respects users' time by making your documentation accessible and reliable.
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:
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.
