Do I need to write documentation?
The article was written based on the report of the same name by Semyon Faktorovich at SnowOne'23 conference, addressed to IT students. If you don't really like to read and you have 50 minutes of free time, listen to this lecture on Youtube.
Can an IT product live without documentation? Let's try to figure it out using the example of a small startup whose team is developing a new innovative system for protecting against cyber threats.
Story 1: the brilliant Oleg and escape to a better life
First there was Oleg, the chief architect. It was Oleg who created the architecture for the project from scratch. The architecture is not described anywhere, but this is not necessary, because all the information is stored in the most reliable place – in Oleg’s head.
Oleg was so important that it seemed that he would always be on the team. But the day came, and Oleg burned out. He decided that he would become a free artist and go to Amsterdam. Before leaving, Oleg gathered his colleagues and explained in detail the architecture. Everyone applauded: Oleg’s decisions were brilliant, without any jokes.
Oleg was released with a calm heart, because he almost always left comments in the code and explained everything to everyone in great detail. Some developers were inspired by Oleg’s example and also went to Amsterdam. The team became a little smaller, the losses had to be made up.
They grieved for Oleg and began to look for a new architect. Dima was soon found and got to work with enthusiasm.
Dima had to collect information about the system piece by piece, carefully read the code and spend hours communicating with the developers. The testimony of colleagues differed in places. In the end, Dima figured out what exactly each line of code did, but he didn’t always understand why Oleg solved the problem the way he did. My colleagues didn't know either.
Story 2: determined Dima and onboarding new employees
Dima didn’t like some of Oleg’s ideas, which no one could explain anyway. In addition, Dima had his own ideas, so he planned to refactor the code. The team expanded to meet this task. Dima explained in detail to each of the newcomers: how the architecture is implemented now; what changes are planned; why exactly like this? Over time, this part of the onboarding turned into a cheerful three-hour stand-up, during which Dima thinks: “It would be better if I was working now.”
Dima understands that it would be nice to write a document for onboarding. And it would be nice to describe the architecture of the system so that it doesn’t work out like with Oleg. And the API should be documented… But Dima doesn’t have enough time for this.
Story 3: Kostya, who didn’t sign up for this
Kostya is a programmer, and he likes Dima’s idea with documentation, but Kostya himself does not like writing texts in human. And why should he? The last time he wrote something like this in his diploma, and then just coded it. Where do you even start writing documentation? introduction?
Sometimes the task falls on Kostya “Briefly describe the new feature to us, you programmer, it’s purely for internal use.” Such tasks irritate Kostya, but he honestly opens the internal Wiki page and spends a long time exhausting the text. The result is so-so, Kostya writes the code much faster and better.
Write a short article for the page or fix twelve new bugs? An easy choice.
Story 4: endlessly resilient Marina
Marina is responsible for technical support and knows the product very well. It helps users understand the settings and forwards any bugs it finds to developers. They often write to technical support, but Marina is very productive – she manages to process all requests in half a day.
Over time, the system acquires new features, new services are added, and old ones are cut down. The number of requests is increasing exponentially. Now Marina is busy all day, and she doesn’t have enough time to drink coffee.
Marina calculated: if things continue like this, she will soon have to work not 8 hours a day, but 19. She asks to hire someone to help her. The requirements for a newbie are modest: he will simply have to copy Marina’s ready-made answers, since many user questions are repeated.
Story 5: proactive Vadim and his rules of thumb
Vadim is the supreme manager. He distributes tasks among team members and monitors their completion. It's not that Vadim is against documentation, it's just that he uses Eisenhower matrix, it is important for him to deploy new features. Documentation is not a priority for Vadim; no one reads it anyway. And this is a non-core activity for programmers – writing articles.
Once upon a time, Vadim already hired a specialist who wrote user documentation for the team in accordance with GOST, this documentation has even been preserved. Vadim remembers Pareto's law and convinces himself that some documentation is much better than no documentation. Even if it was last updated under Medvedev, and it says: “There is no API dock, but you hold on in any unclear situation, write to Marina.”
Story 6: code, text and robots
Nobody wanted to write to Doc, but the technological singularity had already arrived. Therefore, Kinolai Orinov joined the work – man and neural network. Kinolai generated texts much faster than Kostya. “Just what you need!” – everyone thought.
True, in order for Kinolai to write documentation for an innovative system, Kinolai must first show this system from all sides. In other words, you will have to let someone else’s AI into your proprietary code base.
This decision was considered unsafe: you never know what Kinolai has on his mind.
Story 7: how could it be?
It seems that the team has accumulated tasks that only one person can handle:
What would have changed if Danya had started working right away?
Knowledge about architecture would be preserved in documentation and to Amsterdam with Oleg didn't leave. There is staff turnover in any team, so it is safer if important knowledge is concentrated not only in heads, but also in documents.
Dima, who accepted the post of chief architect, would find such documents very useful. Documentation is more reliable than code: Dima could quickly study the structure of the system and understand Oleg’s ideas. Even from the most detailed comments in the code, Dima would not have understood why such a technology stack was chosen. Also, when transferring ideas from your head to code, bugs almost always arise, but when transferring them to documentation, as a rule, there are no bugs.
Perhaps, thanks to this knowledge, Dima would refuse refactoring.
Danya would design an internal knowledge base, understanding the needs of the team. The knowledge base would also store Briefly described new features, and onboarding documents. Dima wouldn’t have to become a part-time stand-up comedian, and programmers like Kostya would fix bugs with peace of mind.
Internal documents save the team a lot of time. The knowledge base, as a single source of information, is an excellent alternative to endless questions in Slack about the same thing. The time saved is money, which the management in the person of Vadim would be very happy about.
Danya would update and maintain user documentation. Technical support in the person of Marina would thank him: there would be fewer stupid questions, and her working day would end on time.
Good user documentation significantly reduces labor costs and removes unnecessary burden from technical support. This would also please Vadim, because cloning Marina turned out to be a little expensive.
And Danya would have become friends with Kinolai, because with his help it would be possible to automate part of the work. It’s true that it won’t be possible to force robots to write documentation yet.
Neural networks have indeed already learned to write coherent texts, but documentation is not just text. To write this text, you need to know not only the subject area itself, you also need to understand the context, the audience, its needs and level. Perhaps one day Kinolai will learn this too. But by that time he will also learn to write code, and then the whole team will be able to go to Oleg in Amsterdam.
But that is another story.
If documentation is vital for your project, come to us at documentat.io. We develop custom technical documentation and provide technical writers for outstaffing. And we also learn to write documentation — perhaps with the help of our courses you can raise your own Danya.
