The documentation will not write itself. Christian Heitzmann tells us why it is crucial to write good documentation in high-quality software engineering.
10.09.2024, 21:37
with Christian Heitzmann & Greg Tomasik
Good day Christian. Thank you for taking part in our interview format. Would you mind giving a brief overview of your career journey - how did you get started in tech, and what were the milestones that guided you to become the owner of SimplexaCode AG?
Sure. My career has always followed two tracks. One track is, of course, software development, which began with hobby projects at school during the 90s. Later, I earned my Master of Science in Computational Science and Engineering from ETH Zurich.
The other track is teaching. A few years after my degree, I started missing university, so I went back to earn Teaching Diplomas in both Computer Science and Mathematics. During that time, I started teaching algorithms and software development at universities of applied sciences, as well as mathematics at public schools. That’s where I also discovered my passion for academic writing.
After doing that for about a decade, I thought: Hey, why not combine these three skills and offer these specific services through my own SimplexaCode AG? Today, I work as a software developer, technical writer, and trainer. Through my company, I mainly offer various services related to software documentation and training in Java and Python technologies.
At which point in your career have you noticed that proper documentation is crucial in high-quality software development?
Very early. My first commercial project, which began while I was still at school, and all academic software theses I wrote afterwards, were always thoroughly documented by me. When I started working in IT after completing my master’s studies, I was startled to find that companies had their applications—consisting of thousands of classes and 6- or 7-figure lines of code—not documented even to the slightest extent. All software developers, even the experienced ones, spent the majority of their day digging through source code, wasting time trying to mentally reconstruct puzzle pieces of the ‘architecture’. I thought: You guys can’t be serious! Is this really the way software development is supposed to be?
What trends do you see in recent years when it comes to software documentation?
My first job was during the time when the public Wikipedia and then company wikis came up. Wikis were quite an improvement compared to Word files, but even back then, they suffered from a problem known as ‘wiki rot’. Or, as I love to recite: The acronym Wiki actually stands for “Where information kills itself”.
There has been a lot going on during the last decade: The realization that effective software documentation has to be close to the actual source code, referred to as ‘docs as code’. The evolution of lightweight, i.e., easy-to-write and read markup languages like AsciiDoc, reStructuredText, or Markdown; though I strongly discourage using the latter. And a lot of tools like Kroki, which supports several diagram syntaxes, and organizational frameworks like the C4 Model or arc42. As an introduction to the world of lightweight markup languages and diagrams as code, I recommend reading my article “Markup Languages in Software Documentation”. One has to keep in mind that every ‘doc stack’ is different, much like tech stacks, and depends on the environment and the needs of all stakeholders.
So the solutions are there, and whoever has made bad experiences with software documentation 10 or 20 years ago: You can forget about those! Things have changed. Software documentation and its tools are here to help, not to burden you.
Do you think that AI tools will improve the completeness and quality of software documentation, for example by assisting with writing? Or rather the other way around: that we will end up with tons of undocumented AI-generated code?
You shouldn’t have asked the second question. If I can’t sleep tonight, it’s your fault! 😄
Automated documentation can only document the obvious. 20 years ago, it was Doxygen, today it’s ChatGPT and similar tools, trying to save what can be saved by reverse engineering. To be honest, nobody needs to explain what the code does. We can all read source code. However, documentation and comments are helpful when they provide an overview and shortcuts, like when a block header tells me what the next 10 lines of code are about, so I don’t have to go through them. They are also helpful when they provide context and reasoning: Why was it done this way and not another? What should the reader be aware of? What are the consequences of doing something this way or another? And so on. These are all things that only a human can know.
Just take a look at the Java SDK or any exemplary Python module. After studying its description, do you still need to look up the code? Can you imagine any AI being able to write such documentation?
To finally answer your second question: Copying code that one hasn’t fully understood, whether it’s from StackOverflow or any AI, should be regarded as the worst crime in software development.
What would you say about the popular approach that the code should be self-documenting, and thus that comments are a bad practice?
Self-documenting code is an illusion. It seems like the perfect excuse, but I’ve never seen it work in practice. Even the cleanest code might only describe a brick, but not the house built from it. Clean code is a prerequisite, not a substitute for documentation. You can’t have one without the other.
Documentation is more than just comments. There are several levels or ‘altitudes’, as I like to call them, with comments located at the lowest level. The ultimate goal of effective software documentation is to avoid having to look at the source code as much as possible. See the JDK or Python examples I mentioned earlier. A few days ago, I looked into the source code of the seaborn Python plotting module, because I needed the hex codes of its colorblind palette. I think it’s been the first time in years that I had to look something up directly in its codebase.
If you really need to access source code, then the higher-level documentation should guide you to the place where you need to do your work. When you’re at the place you should be, then comments can be very helpful in explaining what is going on and, most importantly, why the things are as they are.
Developers often claim that the documentation gets easily outdated because it’s hard to keep it in sync with constant code changes. Is there a reliable solution to prevent it?
If the code updates, then the tests break, and you need to update them, but there is no such thing for docs… or is there?
Yes, a few things can help prevent this.
First, keep the documentation as close to the source code as possible. That’s part of the aforementioned docs-as-code approach. The closer the documentation is to the source code, the lower the risk that developers overlook necessary documentation changes. For example, take a look at Javadoc block comments, which are very close at hand. And then compare it to Confluence pages or any Word files stored on SharePoint, where developers are often unaware that they even exist. And they can’t be blamed for that…
Then, include all documentation-related tasks in your Definition of Done. A checkbox for “Documentation created or updated” should be part of every pull request code review. Admittedly, almost every company I’ve seen has this theoretically written down, but depending on the reviewer, it’s often treated as a low priority or even completely ignored. So yes, there has to be some discipline, there’s no way around it.
What I always suggest is having few, but responsible people for all documentation-related tasks. They could be called ‘technical writers’ or, more playfully, ‘doctators’. This doesn’t mean they have to do all the writing themselves, but they should at least keep an eye on every application change and tap developers on the shoulder if any changes attempt to bypass the necessary documentation changes. Another reason I suggest such a specific role is that many developers don’t like writing documentation, and an even larger portion cannot write it well. So, before the topic is completely ignored, or the documentation becomes an unusable mess, assign it to someone who is both willing and good at it.
As a rule of thumb, the more effort you need to put into passing an exam, the more valuable it is. ‘Certificates’ that result from Coursera or LinkedIn videos which you can watch during dinner are pretty worthless, especially since they don’t provide any proof of performance.
When it comes to programming languages or foundational software frameworks, check if the company behind them offers official certifications. For example, Oracle offers certifications for Java, and VMware does so for the Spring framework. Python doesn’t have a company behind it, but the Python Institute, which is part of the American-Polish OpenEDG Open Education and Development Group, stepped in a few years ago and seems to do a pretty good job.
Sometimes, you have to google and do some research to determine if a certification is well-established. I’m currently researching certifications in the JavaScript/TypeScript and Angular area. One sign of a reputable certification can be if the exam is offered through a Pearson VUE testing center. I’m not claiming that certifications via Pearson VUE are automatically good and those outside of it are automatically bad. However, it can give you an impression of its size and standing in the market.
Are companies valuing and recognizing the certification of candidates, or are they rather nice to have in the recruitment process?
When I applied for my first job after earning my master’s degree, it helped me a lot. Not only had I just finished a computer science and engineering program, but I could also prove that I knew Java pretty well, which isn’t necessarily the case for all university graduates.
Today, 17 years later, tech stacks have changed, companies have changed, and candidate profiles have changed. Certificates can be one of several factors that help you stand out. While certificates don’t guarantee that a candidate is truly proficient, they do increase its likelihood. Conversely, the absence of certificates doesn’t imply that a candidate is incompetent. However, I personally don’t understand why seemingly proficient, experienced people in a particular area don’t invest some hours in getting their competency validated by an official certification. If they were really that proficient, then it would be a matter of only a few hours, and if they find themselves having to invest more time, they probably haven’t been as proficient as they always thought they were.
Speaking about companies who are searching for a jack of all trades, how often do you see this approach in the Swiss or German IT job market?
I often see that job ads are increasingly becoming a collection of ‘tools’, combined with arbitrary years of ‘experience’. As a reader, this raises several questions: Why do you have so many languages, frameworks, and tools? Are you really that chaotic? Have you never consolidated or cleaned up your tech stack? Do you value “X years of experience with language/framework/tool Y” more than fundamental competencies? University graduates aren’t necessarily competent for what they studied, but rather because they studied. Don’t you think that framework A and tool B can be learned within a few days or weeks? What kind of training do you invest in your employees—if at all? And why is the fundamental competency of ‘documenting’ missing from your job ad?
What was the worst code that you have seen in your career?
Aside from the already mentioned totally undocumented big ball of mud that can only be tackled by line-by-line reverse-engineering, working with custom-built frameworks that try to replicate the functionality of well-established frameworks is usually one of the worst. XML parsers and serializers, timers, and ORMs have been around for more than 20 years. No, you don’t need to write another XML parser, and no, you don’t need to create your own doubly-linked list. And even if you invented something that wasn’t available at the time you needed it, replace it as soon as a third-party module becomes established. Hopefully, you layered the application correctly back then…
To summarize, it’s code that makes me think: “If you had only invested a few days into reading a book, you might have saved yourself and your colleagues years of unnecessary work.”
What do you suggest to companies that want to brush up their documentation game?
First of all, put yourself in the position of others. You invested some hours, days or even weeks of hard mental work into developing a particular piece of the application, so don’t expect those who come after you to grasp your ideas within a few seconds or minutes. Your supposedly ‘self-documenting’ code is only self-explanatory to you because you were the one who wrote it.
Next, understand that documentation has different target audiences and altitudes. Architecture diagrams describe a completely different level than source code comments. You cannot create effective documentation without first defining the audience and altitude.
Even if you’re an ‘agile’ company (who isn’t these days?), documentation should be centralized. I know it’s unpopular to say this nowadays, but remember the saying: “Too many cooks spoil the broth.”
Lastly, don’t reinvent the wheel. This applies to both source code and documentation. When it comes to the latter, seek help from someone who is more into the documentation field and understands the common challenges and solutions. A clear analysis and roadmap can save you years of trying to fix it on your own.
Disclaimer: This interview contains some AI-generated pictures. We can assure you that no GPU was harmed during prompt testing.
Christian Heitzmann, MSc ETH CSE, is the founder and owner of SimplexaCode AG, based in Lucerne. He is a certified software developer in Java and Python, holding teaching diplomas in both Computer Science and Mathematics, as well as a CAS in Machine Learning. With over 20 years of experience in software development and 12 years of teaching Java, Python, mathematics, and algorithms, Christian is also a regular contributor to IT journals, sharing his expertise in the field.
Greg Tomasik, Co-Founder & CTO at SwissDevJobs.ch, GermanTechJobs.de & DevITjobs.uk. A Software Engineer with over 8 years of experience working at international companies. Involved in the recruiting industry since 2018, focusing on building transparent job boards for tech talents.
Looking for a new role in tech in Switzerland?