Documenting nodejs applications

There is always a discrepancy between the latest version of the codebase next to its documentation. What if it was possible to sync code with its documentation? This blog is about eliminating some barriers that hinder the documentation to evolve at the same pace as the codebase.

In this article we will talk about:

Even though this blogpost was designed to offer complementary materials to those who bought my Testing nodejs Applications book, the content can help any software developer to tuneup working environment. You use this link to buy the book. Testing `nodejs` Applications Book Cover

The documentation done ahead of code change becomes outdated as soon as any new feature implementation is completed.

The documentation after code change is somehow late documentation. During code change, there is a possibility that critical information is going to be missing, till code change is complete, and documentation is updated.

The right documentation strategy to adopt is the one that reduces a disconnect between the documentation and the code it is supposed to document. Ideally, documentation that goes hand in hand with and as code change happens, as it comes in at the right time and reflects the actual status of the code.

Down below, we present key areas with opportunities to automate the documentation process or to move documentation in sync with code change.

Release notes

Automating release notes makes it possible to continuously delivering release notes as each code version goes out the door.

Versioning

To Automating Version updates, there is quite a catalog of tools that helps to bump version every time a new tag becomes available or a merge is done on a branch tracked as the main branch.

API Documentation

Continuously documenting API. The top comment on every function/method is a good place to start. It is possible to put some effort to update the documentation as new sections of the code get introduced in the codebase. Automation and documentation generation tools help to achieve this. Tools such as documentation.js extract the code comments into human-readable, well-formatted documents, making the continuous documentation a reality.

REST API Documentation

To continuously documenting REST APIs, there are multiple tools and methodologies that have been in place for a very long time. There are tools such as swagger that helps model, as well as documenting the REST APIs as they are being developed. REST APIs documentation have to be beautiful, informative, updated as new endpoints are created or versions are updated. Slate is one of the tools that can help to achieve this goal.

Conclusion

Above are areas that present opportunities to automate the documentation process. How to approach documentation and choice of tools to use are the responsibility of the code maintainer. This article was served food for the soul.

In this article, we revisited tools and methods that help documentation evolve alongside codebase iterations. There are additional complimentary materials in the “Testing nodejs applications” book, regarding good practices around documentation.

References