The Concept of Documentation
The simplest approach to good documentation starts with the naming of classes, functions, and variables – what is known as self-documenting code. Choosing descriptive names significantly improves the readability and maintainability of the code. However, this still requires a basic understanding of the program code, which can be further enhanced with comments.
The next level involves the signatures of functions and classes. They allow you to understand what a function or class does, as well as the values it expects and returns – even without reading the full code. Thanks to modern LLMs (Large Language Models), signatures can be easily derived from existing functions, providing valuable information in the shortest time, often requiring little to no adjustments.
The most important type of documentation is interface documentation. It essentially describes all the signatures that can be used externally. If the software needs to interact with other software, this documentation is indispensable, as it provides the necessary abstraction to work with the software without needing to know its details. Additionally, the documentation can convey other important information. Unfortunately, the motivation, time, or budget for comprehensive interface documentation is often lacking.
Intermediate format
Instead of painstakingly creating or updating documentation manually, tools can automate this process. As long as the code includes basic signatures, these tools can extract the information and convert it into a readable format. The most popular formats for this are Markdown and AsciiDoc, as they offer extensive formatting options with simple syntax. While the tools used to generate these intermediate formats depend on the environment, programming language, and personal preferences, they mostly operate on the same principle.
Frameworks
Markdown or AsciiDoc files are useful on their own, but a complete solution still requires a way to make the documentation accessible. This is where static site generators (SSGs) come into play. They take individual Markdown files and compile them into a static website. This allows the documentation to load quickly, use minimal resources, and remain fully functional.
Docusaurus: The Market Leader
Docusaurus is the established market leader in this field. Developed by Meta, the framework is robust, reliable, and known for its stability as well as its extensive ecosystem.
- Version Control: The framework is distinguished by its version control as a core feature. It allows older documentation to remain available, significantly simplifying support for previous software versions.
- Plugins: Docusaurus can be easily extended with a wide range of plugins to enhance its functionality.
- React-Based: The framework is built on React, enabling seamless integration of existing React components into the documentation.
- Popularity: Due to its widespread recognition, finding information and support is straightforward.
Conclusion: Docusaurus lives up to its name, offering a powerful, extensible, scalable, and stable ecosystem that is ideal for complex projects.
Astro Starlight: The modern and performant solution
Astro Starlight is a relatively new framework that is quickly gaining popularity thanks to its flexibility and performance.
Features
- Performance: Starlight is built on the Astro framework, which delivers only minimal JavaScript. This results in fast loading times and a better user experience, even for very large documentation sites.
- Flexibility: Starlight is ‘framework-agnostic’, meaning it is not tied to any of the common JS frameworks and offers maximum freedom in designing documentation.
- Plugins: Starlight does not (yet) have the same number of plugins as Docusaurus, but the number is steadily growing through the community and official plugins.
Conclusion: Starlight is a young, rapidly growing framework that is particularly well-suited for modern, flexible, and high-performance documentation sites.
Application in Daily Developer Work
Regardless of the framework choice, the documentation can be fully automated via CI/CD pipelines with every deployment. Additionally, manually created documents and a custom design can be integrated to create a tailored solution.
The actual process varies depending on the use case, but can be generalized into a few simple steps:
- First, signatures and selected manual documentation are created.
- This information is converted into an intermediate format (usually Markdown).
- The intermediate format is ‘compiled’ into a static website using the styling specifications.
- Finally, the website is deployed.
This process can be largely automated using the features included in these frameworks.
