Blog

tekom impressions part 2: API documentation and the VUKA world

Daniela Herbold and Ulrike Parson write about better API documentation and solutions for innovative human resources management. more ...

Impressions from tcworld 2017

Part 1: Improvisation, fluff hunt, and videos for technical documentation. more ...

My first time at tekom

I got back from Stuttgart last night and it is safe to say that after three days of action-packed presentations, writing an article is not in the realm of possibilities right now as I try to connect one synapse with another. more ...

The parson mug prize draw #4. Congratulations to the winners

In which city was the parson mug photographed, we asked at the beginning of September. more ...

Flipped Classroom: Make Your Training More Efficient

Paying attention to students with different skill levels requires much time during onsite training. Students with more knowledge can get bored easily. Vice versa, students with less knowledge may get overwhelmed. more ...

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


  • facebook
  • linkedin
  • xing