Gastvortrag am Institute for Software Systems & Engineering der Universität Augsburg, April 2018: Vortrag von Harald Störrle (@stoerrle, Senior IT Berater bei QAware)
Hinweis: Slides sind in Englisch!
Spätestens wenn Projekte ein gewisses Alter und eine gewisse Größe erreichen, stellt sich die Frage nach sinnvoller Dokumentation. Wenn zu wenig dokumentiert wird, kann ein Projektabgang empfindliche Lücken in das Projekt- und Systemwissen reißen. Wenn zu viel dokumentiert wird, kann viel Aufwand nutzlos verpuffen. Was ist das richtige Maß ? Was ist die richtige Form? Welche Themen sollen dokumentiert werden, von wem und in welchem Detailgrad?
In diesem Vortrag werden wir einen Überblick über Formen und Arten von Dokumentation geben. Wir analysieren die Probleme der Dokumentation und diskutieren den Stand der Technik. Wir stellen (vorläufige) Richtlinien zur Erstellung von Dokumentation vor und geben einige praktische Beispiele.
Principal Consultant, Qaware GmbH
Observations & Advice
Munich, April 26, 2018
Categories of and Media for Documentation
Place of documentation
Internal: part of the system
External: separate from the system
Audience of documentation and their concerns
Users: Help and usage instructions
Developers: explanations to support maintenance
Architects: Intent and general structure
Names are part of documentation
Names of units (e.g., databases, tables and columns,
modules, classes, methods and fields)
Names on UI units (e.g., dialog headers, buttons,
fields, default values)
Code: all artefacts belonging to the system, including source code,
executables, and resources (config files, data, icons, …).
The Business Proposition of Documentation
Why would anybody bother writing (or reading) documentation in the first place?
Consider a person ("consumer") who needs to have a question about a system answered to do their job.
There are alternative ways of getting answers that differ in effort and reliability, depending on the system.
Time / Effort
Time / Effort
Scope Reliability Detailed-
Reverse Engineering Executables None Extreme (months) Technology Medium Very high
Debugging Source code w/o
None very large (weeks) Technology High High
Source code with
Large (days) Technology
Availability of (good)
Medium (hours) Domain
Availability of (good)
Small (Minutes) Business High Low
Interview expert Knowledgeable
expert willing to talk
Small (Minutes) all High High
The truth is not (only) in the code
There is more to a system than what it does, and what is written down.
Faulty code tells you what was done ("reality"), not what should have been done ("truth").
Code does not convey the intent (goals, architecture, design decisions) of the system.
Code does not explain its usage application (or its limits), or useful alternatives.
Many stakeholders are not capable (or empowered) to read the code directly.
Think of end-users, pure-bred requirements and UI people, salespeople, management, …
Even to developers, the plain code is often not useful.
It comes with complete, overwhelming detail.
For understanding, however, simplifications and abstractions are vital.
Code is not self-contained, but a web of relations.
Understanding a small part requires understanding (many) other parts first.
This is obvious for crosscutting concerns, but applies to all forms of delegation, call, or inheritance.
Cost and Benefit (1/2)
When there is more fluctuation ("team churn"), documentation
becomes more valuable.
When there are more people, more communication takes place.
When documentation is used more often, more benefit is
generated from it, and the investment is amortized broader.
High project agility incurs high documentation cost and effort.
When the project grows, documentation is just added.
When a project changes, documentation must change.
In the beginning of a large agile project, both forces are at play.
The more often people come into your project, the more benefit
is generated from introductory material.
Wrong documentation is worse than none
Misleading documentation is worse than missing documentation.
It takes time to process, and energy to absorb the mental insult.
It diminishes trust in other documentation, and thus reduces the value of
correct documentation in other places.
If in a hurry, do less, not worse.
If faced with limited available effort, consider instead
creating test cases to support understanding by examples, and to achieve
greater correctness, or
improve your program such that it needs less or no documentation, or
write an higher-level overview document to some part of the system or
Cost and Benefit (2/2)
External and internal pressure will be met by documentation.
Regulatory requirements, e.g., safety in aerospace or medical
devices, or users demanding guidance will result in more (and
Inherent complexity, large size, or high quality requirements
deemphasize coding as opposed to other activities, including
The larger and better documentation is supposed to be, the more
it will cost to create and maintain it.
Documentation (as all forms of knowledge) is subject to decay.
Inflationary processes in technology and domain force old
artifacts into obsolescence.
Generating Code and/or Documentation
When a specification is faithfully implemented, it turns into a
Generating documentation from code (e.g., visualizations,
ToDo-lists) removes maintenance from the equation, but
introduces up-front effort (similar to test cases).
In an MDE-setting, code and documentation (should)
M. Staron: Adopting model driven software development in industry – a case study at two companies.
In: Proc. Model Driven Engineering, Languages and Systems (MoDELS), 2006, pp. 57-72
Don't add too many comments
a large number of comments diverts effort from places
where it is needed more.
the effort is not worthwhile.
there is a high risk of becoming outdated under
Don't say what the code does - the code already does that,
and more concisely (getFoo gets value of Foo-field)
a large number of comments amounts to a large amount of
It dilutes effort and drives attention away from the places
where it is due.
Pointless documentation reduces the value expected from
other documentation, thus reducing its value. [Gary Larson "The complete far side", http://tumblr.austinkleon.com/post/16641876753]
Advice for internal documentation
If you document, do it right.
Avoid trivial mistakes (spelling), use plain language, do not abbreviate or cut corners.
Don't explain awkward logic - instead, improve the logic to make it clear.
Misleading documentation is worse than no documentation.
If available, stick to guidelines/standards.
If there are guidelines for documentation, do follow them, even if you are not convinced by the guidelines.
Sticking to the standard is a value in itself, and more often than not, your own idea is even worse.
Advice for external documentation
Ensure you have a business case.
If no one wants to pay for quality documentation, it's not worth it.
In particular, clients must understand that documentation must be maintained just like code.
If they don't, there is no point (at this time). More investment into their understanding of quality is
Make sure everybody understands and agrees on audience, purpose, and scope of the documentation.
The same problem as with software, the same solutions apply.
Stay away from MS Word if you are considering documents with more than 100 pages.
Know your audience
[Grady Booch: Object-Oriented Analysis and Design with Applications, Addison-Wesley, 1993]
Documentation is hard
Commenting is hard – if a comment is easy, it is superfluous.
Many people will readily agree that finding "good" names for
classes, methods, fields, DB tables, etc. is the hardest part of
This is already part of documentation.
In most domains, there are already well-established terms
Here we must not invent new names, even if the existing
names are bad, outdated, insufficient, …
If there are alternatives (e.g., proper names vs. street names),
we should choose the proper name, and add a comment
mentioning the street name.
The main problem is to learn the new terminology.
Documentation is expensive
Little faults will compound If you buy cheap, you buy twice.
[wiseGeek, http://www.wisegeek.com/what-is-the-broken-windows-theory.htm] [http://argedia.com/wp/think-expensive-hire-professional-marketing-management-consultant-job-wait-hire-amateur]
Documentation is no silver bullet
In many situations, documentation as an activity to share knowledge
is a waste of time and effort.
Often, however, it is useful or even inevitable for an individual to
create documentation in order to understand.
With a little extra effort, other use cases of documentation come
within reach, too.
Even if your documentation is perfect, common sense and
pragmatism are still required.