Seite 3: Tips, Tricks, and Tools

Inhaltsverzeichnis

iX: Aside from AI: What best practices and proven techniques can you recommend to our readers to simplify their documentation process?

Charlotte: In my opinion, documentation should be just as much a part of the development process as programming and testing, and not be left until the end of a huge project. Nowadays, most teams work in an agile way and write code in small increments—so why not apply this to documentation as well? In my company, for example, documentation is part of every ticket in development. So, if a developer creates a change that requires an update to the documentation, it is part of the ticket's definition of done to also update the documentation. In addition to the code review, doc review is another step in the ticket workflow. After an initial phase of getting used to it, most developers have realized that this often only takes five to ten minutes—provided the tickets are defined appropriately small—and that the process of documenting is not that difficult anymore. Just sorting out the documentation at the beginning was a bit of a challenge.

When you write and update documentation for a living system, it sometimes needs to be refactored—just like code. Once a year, I have an Outlook appointment that reminds me to go through the documentation and see where information is duplicated, what can be summarized, whether the arrangement of topics still makes sense, and so on. It also helps to have a template to follow. This reduces the risk of simply forgetting topics in the documentation and is helpful if, for example, you look at the documentation of another project and are familiar with the structure because it is the same everywhere. However, you must be careful that the template does not become too rigid. We have some mandatory chapters in our templates and several optional chapters that we only use when necessary.

And if everything I have mentioned so far would mean too much effort or if you simply can't convince your colleagues: At least don't use a passive voice! A sentence like "Service XYZ is called" is not nearly as helpful as "Service ABC sends an encrypted request with login data to service XYZ".

Alexander: In my opinion, the most important points are simple, recurring structures in the documentation and low barriers to contribute. Templates such as arc42 for system architectures or the topic types from the Diátaxis framework for user documentation provide these structures so that you can start writing straight away and then gradually fill in the gaps.

Technical writers who create structures for a team and provide advice and support are an asset to every project. Traditional tools such as Vale help to standardize the writing style and take the pressure off the technical writers in the project. This gives them time to concentrate on content-related work and knowledge transfer within the team regarding good documentation. Approaches such as documentation as code (docs as code or DaC for short) and tools such as Git lower the barrier for developers to contribute content. They can write content in their development environments and use the same review workflow as for source code.

This approach also paves the way for automation, as it requires no further manual steps after writing and reviewing to publication. However, specialist departments and sometimes even technical writers may find this difficult at first, so support from the developers is necessary at the beginning. Static site generators are usually part of a docs as code concept, although the various tools take very different approaches. From Hugo, which can read several formats and enables very individual sites and directory structures, to Antora, which specializes in AsciiDoc and provides clear structures, allowing authors to quickly familiarize themselves with the system. For documentation, I prefer AsciiDoc over, for example, Markdown. While Markdown is usually sufficient for a README file, I would soon miss tables of contents, cross-references, tables, source code snippets for tested code, and callouts. AsciiDoc can handle all of these things. If a target system absolutely requires Markdown, I can convert AsciiDoc to Markdown, but retain the advantages of AsciiDoc in my writing environment. If I already have documentation in Word or Markdown format, I can convert it to AsciiDoc, continue writing in the new format, and thus benefit from the advantages of AsciiDoc.

Falk: In my view, there are two issues here. On the one hand, documentation should become more of a part of the development process. This means that developers need to see creating and updating documentation as part of their work, just like writing automated tests. They should check changes to the documentation via feedback mechanisms, for example in code reviews, to distribute knowledge. It helps to use developer-oriented tools for writing documentation.

And that is the second point: Documentation should be created and maintained with lightweight development tools according to the documentation as code principle. This includes markup languages such as AsciiDoc or Markdown, as well as storing the sources in a code repository—near the source code—, the use of command-line tools, and automated creation using build tools. You can create graphics with tools integrated into the development environment, such as draw.io/diagrams.net, or even as text formats by utilizing, for example, PlantUML or Mermaid.js.

Gernot: Less is more: Start with a canvas, for example the arc42 canvas. With this, a team can create a feasible starting point in 60 minutes! Some of our teams have even rediscovered the fun in documentation because they were able to produce decent results in a very short time.

Limit yourself to a few images or diagrams and always—without exception—add a short explanation in the form of text or a table. Keep your documentation lightweight, think "documentation diet": From time to time, you can delete parts that nobody needs anymore. Furthermore, you should always first determine which stakeholders require which information. This will help you find out for whom exactly you need to create which documentation. This in turn directly increases the motivation to create and maintain it.

Ultimately, the development team is one of the most important stakeholders for technical documentation: We should decide together as a team what and how we want and should document for ourselves.

iX: And, lastly, what should developers strictly avoid when it comes to documentation?

Charlotte: I can think of several things right off the bat. For example, general sentences that could appear unchanged in any project. Something like "This module implements our company's business logic." I expect that—but which part of the business logic does it implement? Such empty phrases unnecessarily bloat the documentation and require additional mental capacity when reading, without offering any added value. So, either make it more precise or get rid of it!

In my opinion, one documentation for everyone is also a terrible idea. I believe it's important to ask yourself for whom you are writing the documentation. In my experience, the workload is more manageable and the benefits greater if you write several small documentations for different target groups. Developers, for example, are looking for different information than project managers. It is well known that we write a user manual for the users and do not document the information together with the design decisions. But it seems to be a completely new idea that, for example, information about the framework or other technological decisions are irrelevant for the sales department or a non-technical project manager, and should therefore be included in documentation that is specifically aimed at the developers.

Another aspect is documentation that you have to read from the beginning, like prose, in order to really understand it. When someone looks at the documentation, they are usually searching for very specific information and want to find it as quickly as possible. Documentation should therefore be structured to always provide the needed information in one place. In the case of online documentation, this is known as "every page is page one," which means that every page in the documentation should be designed to function as an entry page. By linking to related topics and necessary prior knowledge, users can catch up on their missing knowledge on their own. At the same time, the information they were initially looking for is immediately available.

Alexander: Documentation can only reach its full potential if it is read and understood. To achieve this, it must be written for the right target group. The authors therefore need at least a minimal common understanding of the target group before they create the respective structures for the future documentation. For each iteration, such as testing, documentation is part of the definition of done. It should not be created retrospectively, but in parallel with the software. This way, you lose less knowledge and stakeholders can quickly view new and amended chapters, ask questions, better understand the system and, if necessary, request changes in a timely manner.

Falk: I recommend viewing documentation less dogmatically, but rather pragmatically. If you are doing basic architectural work, such as developing quality objectives, then in my view the basic logging of our work, including a brief description, is sufficient as a first version of the documentation. And a picture is worth a thousand words. That's why a few, not overly complicated architectural diagrams are always more helpful than dozens of pages of text. If, for example, architectural documentation is treated as living documentation, it brings additional value and is more likely to be accepted and kept up to date by all project participants.

Gernot (laughs): How many answers may I give? Well, first of all, formalism, bloat, and bad tools really kill the fun. If you first have to start a virtual machine, then boot Windows inside it, and then start a difficult tool in order to maintain documentation, you will constantly come up with good excuses for not documenting. I also think that documentation sprints are a terrible antipattern: Producing nothing but documentation for 14 days neither advances the system in terms of content nor is it enjoyable for either the product owner or the team.

iX: Thank you for the interview!

The interview was conducted by Maika Möbus, editor at iX.

(mai)