Out of the Shadows: Software Documentation
Four experts share their knowledge on how developers can make software documentation less tedious, more useful, and more enjoyable to write.
(Bild: Stokkete/Shutterstock.com)
(Dieses Interview ist auch auf Deutsch verfĂĽgbar.)
Software documentation can be a hassle—but it doesn't have to be. iX spoke with four experts who share their experiences and offer suggestions for improving the documentation process. Charlotte Scharbert, Alexander Schwartz, Falk Sippach, and Gernot Starke weigh in on whether AI tools can be helpful, which best practices developers can implement, which possible pitfalls they should avoid, and how they can seamlessly integrate documentation into their daily workflow.
Common Hurdles: Lack of Appreciation, Unclear Target Groups and Instructions
iX: The documentation of software and its architecture is rather unpopular. In your opinion and experience, what are the biggest hurdles?
Charlotte Scharbert: I think a major problem is the lack of a standard as it exists for floor plans in architecture or for circuit diagrams in electrical engineering. Of course, we have standards such as UML, but these are rarely used and, in my experience, are only suitable for mapping software architecture to a limited extent. As a result, you often find a confusing arrangement of boxes and lines that nobody really understands after a few months, or the project documentation simply states "we use a hexagonal architecture" with a picture from a Google search—and that's it. Documentation is often only created at the end of a project. Then, it is obviously difficult to remember everything or to reconstruct how something was built. This makes documentation tedious and nerve-wracking. In addition, there are only few tools to quickly and simply create diagrams that can also be easily adapted if something changes. In my experience, graphical tools tend to be frustrating because developers don't want to spend ages moving boxes around. Diagrams as code is a good approach here, but in my opinion it has not yet reached its full potential.
Alexander Schwartz: The perceived lack of appreciation of documentation is a common hurdle. Developers always dislike documentation when they don't see it being read and actively used. This is a good starting point: A web tracking tool can show which parts of the documentation are accessed and how often, while statistics on avoidable customer queries can point to where documentation is lacking. A software architect or a specialist department can show their appreciation of the documentation by reading it and asking questions to understand the system in question. For example, you could ask yourself when you last brought an extract from the documentation or an existing diagram to a planning meeting and actively worked with it, instead of sketching the diagram once again on a flipchart. Documentation can be an investment in the future, but it is sometimes perceived as the opposite: Developers may worry about losing their job if they document too much. On the contrary, documentation helps stakeholders understand the system and encourages new ideas—and new ideas for an existing system are a good way to keep your current job.
Developers often complain about being overworked and that they don't have time to write documentation. Instead, they spend a lot of time explaining things to others that they wouldn't have to explain if there were good documentation. And when reinforcements join the team and there is no documentation, the new team member can soon become frustrated and leave.
In addition, systems without documentation are at a high risk of being cut. In my experience, an inventory of the various systems took place every two years, at the latest. If nobody can explain what the system is responsible for, how it works and what added value it brings, this is usually bad for the future of the system as well as the team. In rare cases, though, such a system will survive purely because others are too afraid to switch it off due to unknown consequences.
Sometimes the lack of habit combined with a high cognitive load is the barrier to writing documentation—not just architectural documentation. If you haven't done this in a long time, it is difficult to spontaneously add the appropriate documentation that would be part of a current software change. Too little structure or even too many formalisms mean that authors have to think too much about the details, rather than concentrating on writing the additional sections or creating the new diagram. Documentation is always unpopular with software architects and other stakeholders if it is not up to date. Nevertheless, they can actively use it, promote it as insurance for the future, and simplify maintenance with simple structures and tools. It also helps to set a good example and contribute yourself if the owners of the documentation agree. I recommend interviewing the knowledge carriers, adapting the documentation, and then having them proofread the changes. This also shows your appreciation for the documentation.
Falk Sippach: There are several reasons for this. For one thing, developers may not always know what they should document, to what extent and in what form. Additionally, if they don't give enough thought to the target group and don't keep the content up to date, the documentation won't be read. And this reduces the motivation to write it. Also, other topics are often more important, while the importance of the documentation is too low. And finally, the typical documentation tools are too far removed from day-to-day work, which makes the hurdles unnecessarily high, especially for developers.
Gernot Starke: Coding and technical tasks are simply more fun. But aside from this fun factor: Teams sometimes receive the unspecific request to "document something," while it remains unclear what exactly they should document and in what depth. Even worse: The target group of the documentation often remains unspecified—and nobody likes to document in vain. If it is clear to me as a developer that I am creating something specific for a certain person ABC, I am much more motivated compared to thinking "nobody will read this anyway".
A third reason for the unpopularity could be high effort and formalism: In my opinion, UML and SysML modeling tools in particular can have poor usability to some extent, making documentation seem like a nightmare compared to lightweight tools like Draw.io. Last but not least, documenting is not fun if the existing documentation is poor or outdated, or if the Wiki is overloaded with unnecessary information.
Documentation Support by Generative AI
iX: Tools based on artificial intelligence (AI)—especially generative AI—can now support developers in many areas of their everyday work, such as in the form of AI-powered coding assistants. How does AI help you with documentation today and how may it help in the future?
Charlotte: We once had the idea of letting AI generate the documentation. I tried it out a bit, at the time with GPT-3.5 from OpenAI, because that was one of the few AI models that we considered due to its terms of use. Unfortunately, the model was not powerful enough for our requirements, which is why the project was initially put on hold. However, there are already plans to revive the topic and try out whether newer AI models are a viable option. At the moment, though, I can't give a clear recommendation.
Alexander: First of all, documentation should be consistent as well as grammatically and syntactically correct. In addition, documentation should, for example, favor lists and tables over continuous text and use active language for good readability. In the past, support tools were usually limited to nagging: This sentence is too long, the verb is in passive voice, and the grammar and syntax are wrong. Gradually, grammar checking has improved, but now generative AI can really help. It can rewrite entire sections, adjust passive to active language and correct grammatical errors. This makes it much easier for authors who have little practice or who write in a language other than their first language to produce high-quality documentation. By interacting with the AI model, they can improve their writing style over time.
Generative AI can also fill in missing image descriptions, which improves accessibility. Sometimes it can also create diagrams for an existing text, which the authors can then modify. It can also create a rough version of the documentation. However, there is a risk that the AI may hallucinate things that the software cannot yet do. Humans have to find and remove such sections during proofreading. If the idea is good, it should be implemented as a change in the next software release.
Once the documentation has been written, it is the perfect input for a generative AI model. If the AI is given access to the documentation, it can then answer questions about the software and help users. It should always provide a link to the documentation alongside the answer so that people can continue reading there.
Falk: I think we should be cautious for now. AI is only as good as our input. And we must always check and question the results. However, tools like ChatGPT can support us in creating documentation. Be it as a patient sparring partner to discuss content and suggest alternative formulations, or to create textual diagrams according to the "as code" principle with the documentation tools such as PlantUML. ChatGPT, for example, provides plugins that can create architectural diagrams based on our input.
Gernot: I'm sure we've all tried to have generative AI explain code fragments to us—assuming the AI is compliant with data privacy regulations. My own experiments in this regard have been quite successful, and the AI has even untangled heavily nested passages for me. So far, however, this has primarily worked on low-level constructs, such as individual functions or methods. AI has not yet been able to give me an understanding from a bird's-eye view, at least not yet (as of April 2024). AI is still unable to provide an overview on a large scale. In terms of arc42—an open-source, pragmatic approach for documenting and communicating software systems—, this means neither a context delimitation nor a top-level building block view. AI also fails miserably when it comes to the reasoning that led to certain decisions. For my practical work, this means that I should concentrate even more than before on the high-level overview and the more strategic topics.
But it's worth taking a look at requirements engineering: AI has proven to be amazingly good at phrasing specific quality requirements in a measurable and testable way. These types of requirements—such as usability, performance, security, and maintainability—are among the most important parts of technical documentation because they link requirements, architecture, and development. There are almost one hundred examples of concrete quality requirements at quality.arc42.org, of which presumably around a dozen were created with the help of ChatGPT on the basis of GPT-4.
Tips, Tricks, and Tools
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)
