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.



tcworld 2018: What's New with iiRDS?

iiRDS was one of the central topics at the tcworld conference 2018: at the new iiRDS Café, in lectures, showcases, and tutorials. There was also a discussion on Twitter, among other things about the name, which is so difficult to pronounce. more ...

tcworld 2018 part 3: Creative online videos for technical documentation

Clear the stage! At the beginning of his workshop "Creating thrilling online videos", Stephan Schneider showed two pictures. more ...

tcworld 2018 part 2: Virtual and actual highlights

The sun is shining brightly as I arrive for my first tekom. Inside, the conference is already in full swing. Two days of presentations, workshops, fair impressions and conversations await. more ...

tcworld 2018 part 1: Legal Requirements vs Readability

At this year's tcworld conference, there were a lot of discussions about standards and regulations for technical documentation. Experts such as Jens-Uwe Heuer-James and Torsten Gruchmann came together for a panel discussion where the following was repeatedly said: "We need an IEC 82079-1!" more ...

Working in self-organizing teams. Or: how we get rid of management

Today's world is VUCA : volatile, uncertain, complex, and ambiguous. Companies are facing complex challenges such as Industry 4.0 and the Internet of Things. Those who do not respond fast, may be driven out of the market. more ...
  • linkedin
  • xing