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.
