Since the announcement of Nubus at the Univention Summit in January 2024, Univention has invested a lot of work in creating the accompanying documentation. This blog post gives an insight into how product documentation has developed at Univention in general. And which principles Univention applied to Nubus in particular. It’s for people with an interest in the value of documentation for software products. And it’s for people with an interest in technical writing.
Nubus for Kubernetes is the newest member of the Univention product family. It fits in well with the family tradition of being a complex product, because it consists of many parts. It runs on Kubernetes, an open source system for automating the deployment, scaling, and management of containerized applications. It integrates a lot of open source software to provide identity and access management, a graphical management UI, a portal, and many more.
Over the last twelve months, the Nubus team has been working hard to make Nubus for Kubernetes publicly available and mature. As the technical writer who wrote most of the documentation, Nubus has been the focus of my attention.
Table of Contents
Importance of Documentation
Documentation is an integral and important part of a complex product. It allows people to learn about a product at their own pace and intensity. They can take a look, without obligation, to see if the product meets their organization’s needs, and come back with questions that need answers in a face-to-face conversation. It helps a vendor to relieve the support team and to scale, because they don’t have to explain the same things over and over again in one-on-one conversations. Without documentation, it’s hard to even get started.
For me as a technical writer, product documentation is a matter of respect and appreciation for the people who use a software product. Documentation is part of the product lifecycle. It’s part of the definition of done in agile software development. It’s the historical record of the existence of features and use cases. With this perspective in mind, the “Docs, or it didn’t happen.” mantra of the worldwide Write the Docs community of technical writers comes to life.
Changed Approach to Documentation
For Univention, Nubus has provided an opportunity to design product documentation from scratch. In the following sections, I’d like to explain a few principles.
Scope
The following questions and their answers define the scope of the documentation.
- Who is the reader?
- What does the reader want or need?
- What does the reader know?
- What information belongs into the document? And what information doesn’t?
- Where does the published document locate?
- Who is responsible for maintaining the document?
Having clear answers to these questions is really helpful for anyone involved in a documentation project. It’s also especially important to remember them when talking about and planning for additional content over the course of time. The scope helps to decide on the detail level of the content, or where planned content actually belongs.
Without a clear scope and audience, content feels fuzzy, or the level of detail jumps from low to high, to name a few.
Agile Development
As a software company, Univention uses agile software development methods to develop the software iteratively. Agile software development also affects the way technical writers create documentation. Just as software can hardly be considered finished, neither can its documentation.
Univention publishes documentation content when parts that logically belong together, such as a section or a new chapter, are ready, not when the entire documentation is complete. Interested parties can already familiarize themselves with the product or its architecture and continue with their thought processes. Univention product documentation follows the principle of release early, release often, a software development philosophy with focus on frequent releases to create a tight feedback loop between the content creator and the consumer.
Docs as Code
A requirement for agile development is process automation. For documentation, this means applying Docs as Code, a philosophy about writing documentation with the same tools as software code:
- For planning, Univention uses epics and issues.
- A text editor for creating content written in a lightweight markup language.
- Git for committing changes to a source code repository.
Automation in CI/CD pipelines converts the content for the target formats such as HTML and PDF. It also provides quality assurance such as spell checking and link validation. Technical writers can rely on automated processes to free their minds to focus on content.
For content review, feature branches and merge requests help to increase communication efficiency. For example, similar to software development, content comes in so-called feature branches in the source code repository. Content can be a chapter, or a change to existing content. A merge request contains all necessary information for a change, such as a summary about the change, the commits that make up the change, details about what changes, and who made the change to which files. During the review process the reviewers see the content in their web browser. They can comment on sentences or sections, or they can suggest changes. A merge request is the central piece that holds together all communication about a content change. It increases the communication efficiency, because it’s a single point of contact and it avoids media disruption. Gone are the days when writers and reviewers exchanged content feedback through email with attachments.
Close Contact with Subject-Matter-Experts
Staying in close contact with subject-matter-experts is a principle that keeps the technical writer working. Technical writers need direct and regular contact with people in the organization who know a subject well enough for product documentation. To produce quality content, a technical writer must understand a subject. Understanding means reading and asking the right questions of the right people.
At Univention, the technical writer attends the daily team meetings for the duration of a documentation project to ask questions, get answers, and continue to work on the content. Interviews with subject-matter-experts are an efficient way to validate research findings and add subject matter expertise without requiring the expert to invest too much time. Subject-matter-experts are also part of the review process to ensure that the content is technically correct.
Standardized Notation for Visualization
The architecture description of Nubus for Kubernetes uses a lot of visualization to support the reader’s understanding. Univention decided to use the enterprise architecture notation ArchiMate, because it provides the right fit for the intended level of abstraction. The benefit in contrast to just using lines and boxes is the well-defined semantics for each concept in the notation language. A technical writer can focus on describing the meaning of the visual without delving into the semantics. A reference to the specification is sufficient for readers who want to go in deeper.
Available Nubus for Kubernetes documentation
Personally, I like ArchiMate’s ability to visualize natural language and how it helps me to think deeply about a topic. ArchiMate is strong in covering the schema of who does what with whom. It also helps in conversations with subject-matter-experts, because the actively acting part in software isn’t always evident.
Style Guide
A style guide is one tool for ensuring consistency throughout your product documentation. It describes the general principles of product documentation, such as voice and tone, accessibility, audience, or how to deal with timely statements, and decisions that have already been made, such as how to write a term: boot loader or bootloader. Both terms are correct if you look them up in a dictionary. You can find several style guides on the internet, even under a Creative Commons license.
Together with a prose linter, such as vale, the style guide unfolds its full potential to reveal violations in the content. With the prose linter integrated into the text editor, the technical writer sees style guide violations directly in the content during the writing process. Linters are static code analysis software tools. Software engineers lint their software code to identify programming errors, bugs, style errors, and suspicious constructs. Prose linters work similar, but with text.
Documentation for Nubus for Kubernetes
The Nubus product documentation comprises quite some content. It addresses various audiences, such as operators, DevOps engineers, support, and software engineers. It provides different perspectives to explain the construction of the product, and how to use it.
Available Nubus for Kubernetes documentation
You find all published documents in the Univention Nubus section on the Univention product documentation site.
- The Architecture Manual describes the parts and their construction in Nubus for Kubernetes. It addresses architects, support engineers, and DevOps engineers.
- The Operation Manual describes how to operate Nubus for Kubernetes. It addresses DevOps engineers and operators.
- The Customization Guide describes how customize and extend Nubus. It addresses software engineers and DevOps engineers.
- The Release Notes cover the changes to each version of Nubus for Kubernetes. It addresses DevOps engineers and operators.
Generally, on the documentation site you can navigate to the needed document or use the integrated search across all documents.
However, not everything that was planned is available yet. The focus was on the operators and DevOps engineers, enabling them to get Nubus for Kubernetes up and running in their cluster. As Nubus evolves with each release, the documentation receives content that describes the respective use cases. At the same time, the documentation includes content aimed at the audience of software engineers who want to connect their solutions by customizing and extending Nubus.
Conclusion
To conclude the evolutionary journey through product documentation over the past twelve months, here is the summary of some lessons learned:
- Focus on the reader.Your readers want to satisfy their information need. As technical writer, it’s your responsibility to provide the documentation that they need to get their tasks done with your product.
- Use automation for repetitive tasks for building the final formats of your documentation, or publishing the content.
- Create and use a style guide for documentation and then adhere to it. Use prose linters to help you apply the rules.
- Use standardized notation for visualization.
- Get to know your text editor and know it well. It boosts your efficiency.
Technical documentation is an interdisciplinary topic. At Univention, it’s a great advantage to have a dedicated role that’s solely responsible for product documentation. The role focuses on just documentation. And the development teams know that this role is taking care of product documentation. It frees their minds and helps them to focus on software development. However, it doesn’t mean that software developers can’t or don’t contribute to documentation.
