Documentation – The Necessary Evil?

It’s midnight, somewhere in Germany. Anna is sitting at her desk, head in her hands. She is staring at the computer screen. She has just started working for a company that develops custom add-ons for an out-of-the-box financial software solution. For developing the add-ons, Anna is supposed to use the API (application programming interface) of the software. Little does Anna know about the API’s structure, its interfaces, and its functionality. The API is poorly documented. The missing documentation costs her and her employer time and money and the project gets into a precarious situation.

checkmarkGood API documentation …

  • explains basic concepts and functionalities,
  • presents important use cases,
  • describes in detail frequently used interfaces.

Same time, somewhere on the American continent. There is a knock on Jim’s door. His assistant Sandy enters the room. Jim works as a project manager for the company that sells the financial software for which Anna is supposed to develop the add-on.

Sandy looks alarmed. “I just got another angry phone call from one of our technical partners. He says they will quit the partner program because the API documentation is so poorly written that it takes them way too much time to develop their add-ons.”

Jim is rolling his eyes. This documentation has become a nuisance. They are losing money. He will have a word with one of the software architects. On his way through the building, Jim passes the meeting room. Through the glass door he makes out Ben, the leader of the software development team. Ben is drawing a diagram on a whiteboard. He seems to be trying to explain that diagram to a young man who sits at the conference table. The young man is listening intently.

Jim sticks his head through the door and says hello.

“This is Michael, our new intern”, introduces Ben the young man.

“Welcome to the team”, Jim says. Then he looks at the whiteboard. “Ben, how many times have I seen you draw that diagram?”

Ben’s face turns red. “I am doing this once or twice a month”, he answers. “Whenever we get a new intern.”

Jim quietly calculates how much time Ben spends on this every month.

“Why don’t you write all that into a wiki?”, Michael suggests and points at the whiteboard. “It will save you a lot of time. I could help your set up a wiki.”

checkmarkGood architecture documentation …

  • explains the key functions of the system,
  • introduces all the subsystems,
  • shows the correlations between components,
  • explains important concepts,
  • visualizes software layers.

In the office right next to the meeting room, Tony is starting up his computer. For days, he has been trying to learn about a new subsystem of the software. The software engineer who developed it, left the company a week ago. That guy knew everything about the subsystem, but never bothered to write anything down. All his knowledge was in his head. Now Tony is desperately trying to understand the functionality of the subsystem by interviewing coworkers and reading code. But he is losing valuable time. He should have finished customizing one of the subsystem’s components by now.

Good low-level documentation …

  • helps new staff members to get to know subsystems,
  • presents expert knowledge,
  • indicates the weak points of the system,
  • ensures scalability of the system,
  • combines detailed and general information for valuable and up-to-date documentation,
  • is created in an iterative development process,
  • avoids redundancies through its modular structure,
  • follows code conventions and developer guidelines,
  • explains important terms in glossaries.

Anna, Michael, and Tony are all facing the same problem. They need to work with a software that they don’t know or so far may have seen from a different angle. The information they have is outdated, incomplete, and poorly edited.

Sometimes the code provides information about how a system works. But not everyone can read code or has access to it.

A technical writer can help. Technical writers identify the target groups that work with the system and study their requirements. Together with the software engineers, software architects, and products managers they develop concepts, templates, and best practices for creating the documentation. They also know which documentation type and processes to select. And they know how to create documentation in a fast and cost-efficient way, documentation whose content is valuable and stays up-to-date.

Technical writers actively support software engineering teams. They ensure that the documentation is of high quality, complete, and consistent. As members of the interdisciplinary development team, technical writers are integrated in the development processes and participate in stand-ups and code reviews.

Creating good documentation does not mean creating more documentation. It means creating the right documentation that becomes a valuable information product. What constitutes "right documentation" can be different and depends on the project. Therefore documentation processes are individually tailored to customer needs. They are never standard solutions. They have to be integrated into business processes. If that happens, documentation turns from necessary evil into an important tool and provides high value.

Our knowledge base article Developer Documentation – The Necessary Evil? summarizes our experience from various software documentation projects. It presents the characteristics of good developer documentation and describes how to document a software system comprehensively and with little effort. See also Documentation for Software Engineers.


Add comment


tcworld conference report, part 4: About a terminology workshop and error messages that don't scare us

In our last report about the tcworld conference 2019 we talk about an enlightening terminology workshop  and error messages that scare us. more ...

Is AI a chance or a threat for technical communicators?

The phrase artificial intelligence (AI) is a mystery. Everyone immediately associates something with it, but the ideas are rarely identical. more ...

Jumping in at the deep end. tcworld conference report part 2

I'm an old hand at the tcworld conference and shouldn't be too excited when giving a talk. But when Dieter Gust and I brought our crackpot idea to the stage, I started to feel queasy. What were we thinking? more ...

When three technical communicators go out to dinner. tcword conference report, part 1

When three technical communicators go out to eat at an Italian restaurant after an inspiring but exhausting day at the tcworld conference, the following can happen. more ...

The iiBot gives instructions

Imagine a chatbot that gives precise instructions - live, based on the use case, and tailored to the service technician's qualification. more ...
  • linkedin
  • xing