Software Documentation in Open Space at seacon 2013

Last week, I attended seacon 2013, the software developers’ conference for northern Germany: great speeches, fast-paced pecha kucha presentations – and two open space discussion slots. The participants selected the topics for the slots. It took me a little bit of courage to suggest my favorite topic: technical documentation or, to be more precise, “How much documentation do agile projects need?”

I needn't have worried. Not only did many people attend. We also had a lively discussion that led to amazing results. Let’s see what we got:

What kind of software documentation do you write?

  1. Test documentation. Tests perfectly display the behavior that is expected of the software. In behavior driven development, scenarios are the basis for automatic tests. They are already considered meaningful documentation.
  2. Requirement specification, for example, as user stories
  3. Architecture documentation
    • Most importantly, we need to document software design decisions so that we can later refer to them. Example: Why did we select that algorithm, why did we do the implementation that way? Easy to document in a wiki.
    • It’s a huge effort to manually keep models and UML diagrams up-to-date. If possible, generate the diagrams automatically, class diagrams, for example.
    • Arc24 is known, but most of the participants do not document so comprehensively.
  4. Source code comments. Here we heard many different opinions. Some thought that classes and methods do not need to be commented if you use descriptive names and naming conventions. Others considered code comments necessary. Everyone agreed on the following:
    • Define naming conventions and stick to them. This way you get names that are consistent and descriptive. Adjust names to domain language.
    • Document external APIs, which means that you will usually also write code comments.
    • Use source code comments only if necessary (minimalistic approach).
  5. User documentation
    • User documentation must be based on user tasks. That is why user stories are so perfectly suited as the basis of user manuals.
    • Technical writers write documentation for users, administrators, and software engineers. They should be part of the interdisciplinary scrum team. Among many other things, they can define terminology and standardize terms and structures.

When do you write documentation?

  • Write and update documentation during the project
  • Include documentation in the definition of done so that it becomes part of the development process.
  • At the end of the project, update the documentation so that it reflects the final development status.

How do you write documentation and which tools do you use?

  • Documentation must be written for a target group. It should be tailored for the software engineer, the tester, or the end user. Select content and type accordingly.
  • Documentation must be minimalistic.
  • Only high-quality and up-to-date documentation is useful. Documentation represents a business value.
  • Some use wikis for documentation and scenarios. Examples are MediaWiki, Semantic MediaWiki, and Confluence. Yet, diagrams can often not be inserted directly into wikis. They have to be created with different tools and later be imported as images (png, for example).  It is difficult to keep two versions in-synch. A possible solution: Signavio can embed BPMN diagrams in Confluence, for example.
  • Some solely use UML tools to keep all information in one source.


Add comment


Technical Writer - A Career Path for Social Scientists

What can you do with a degree in social science? Fabian Klopfer has a master's degree in History and decided to become a technical writer. more ...

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 ...
  • linkedin
  • xing