Estimated reading time: 6 minutes
We recently launched a new documentation website, which serves as a comprehensive and dependable source of information for all our customers. The people behind the operation are our educational team, led by Florian Haas, who provided valuable insights into the project’s development process in a recent interview. This article summarises the broad brush strokes behind the team’s work throughout the project. If you want to learn more about its technical side, Florian has written a comprehensive article on his website called Making docs with MkDocs.
xahteiwi.eu – Making docs with MkDocs
At work, my team and I built and launched a new documentation website, built on Material for MkDocs.
The official launch of the documentation website took place on February 20th, when the “beta” markers were removed, indicating that the platform was ready for use. However, this milestone was the culmination of months of hard work. The team began with preliminary research in mid-2022 and ramped up their efforts in October of the same year to write the documentation.
Table of contents
Choosing the Right Framework and Format
The team’s primary goal was to create authoritative and dependable documentation for Cleura Cloud. They adopted the Diátaxis framework, an industry standard, to guide their approach. One of the critical early decisions was selecting a documentation format. They ultimately chose Markdown for its balance between richness of expression and intuitive use. Florian explained, “Markdown lets you write good documentation, but it also lets anyone write good documentation without having to familiarise themselves with some gnarly syntax.”
Image: https://diataxis.fr/
Encouraging Collaboration through Open Source
The choice of format was essential because the team aimed to involve as many contributors as possible. Tech writers are often stretched thin, and by enabling developers, consultants, QA personnel, and even customers to contribute, Cleura can maintain a comprehensive documentation repository. The team decided to host the documentation on GitHub under a Creative Commons license, so anyone can file issues, send pull requests, and be assured that their contributions remain free for all to use.
Florian elaborated on the importance of the license.
“If we encourage contributions from Cleura Cloud users and customers, then we also have to give them a guarantee that their contributions will always be available for free to use, for them and others.”
The Creative Commons Attribution Share-Alike license requires anyone using the documentation to credit the original source, provide a link, and share their modifications under the same terms.
Implementing a Toolchain and Workflow
With the format and license decisions made, the team’s next challenge was selecting, testing, and implementing a toolchain to bring their vision to life. The team built a robust and efficient platform for Cleura Cloud documentation using Material for MkDocs. The platform is driven by a workflow where every change undergoes review and passes through a CI pipeline before being pushed to a static website. The workflow integrates quality control tools, such as linters, for maintaining a consistent documentation style and a link checker to avoid dead links.
Image: https://squidfunk.github.io/mkdocs-material/
Linters
Linters are software tools that analyze and check the source code for potential issues, such as syntax errors, formatting inconsistencies, and adherence to coding standards or best practices. In the case of Cleura Cloud documentation, linters ensure that the documentation style remains consistent across different authors and contributions. This helps maintain the overall quality and readability of the documentation for our users.
https://en.wikipedia.org/wiki/Lint_(software)
The team can streamline collaboration and manage contributions effectively by hosting the entire documentation process on GitHub. Using GitHub Actions allows for seamless integration of automated checks and continuous deployment of the documentation website. The platform’s design facilitates collaboration and ensures that high-quality documentation is maintained throughout the project.
Harnessing the Power of Teamwork and Asynchronous Collaboration
While automated checks are essential for maintaining quality, Florian emphasizes the importance of human review in the documentation process. The team relies on each other for feedback and revisions, fostering a supportive environment where they can learn and grow together. The natural context-switching between writing and reviewing others’ work creates a continuous flow that enhances productivity.
After implementing the toolchain and designing the workflow, coordinating the people writing the documentation is the real challenge. A significant contribution came from Christos Varelas, a colleague from Greece, who wrote most of the new material over four months. The workflow proved successful in attracting contributions from many others within the company. Florian shared that the documentation repository currently contains 44,000 words, equivalent to approximately 100 single-spaced A4 pages.
The documentation team’s collaboration is primarily asynchronous, working remotely and communicating through issue trackers, email, and the documentation review process. They hold one meeting per week and minimize the use of chat to avoid interruptions and maintain a steady workflow. The team has successfully created a culture of continuous improvement, with employees across the organization readily contributing to the documentation without being prompted.
Future Plans for docs.cleura.com
With the official launch of the documentation platform, the team is far from finished. They now focus on expanding background documentation, or “explanation,” according to Diátaxis, and supporting the Gardener public beta by providing more comprehensive documentation. They are also working on a Cleura Cloud Academy course to help colleagues and customers understand Gardener better. Additionally, the storage team has submitted new how-to guides for review and publication. With these ongoing efforts, the educational team continues to make strides in providing valuable resources for all Cleura users.