Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Pragmatisch dokumentieren - ein Vorschlag


Published on

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.

Published in: Software
  • Sie können Hilfe bekommen bei ⇒ ⇐. Erfolg und Grüße!
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

Pragmatisch dokumentieren - ein Vorschlag

  1. 1. Harald Störrle Principal Consultant, Qaware GmbH Documentation Observations & Advice Munich, April 26, 2018
  2. 2. 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, …).
  3. 3. The Business Proposition of Documentation QAware 3 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. Approach Available Artefacts Time / Effort (producer) Time / Effort (consumer) Scope Reliability Detailed- ness Reverse Engineering Executables None Extreme (months) Technology Medium Very high Debugging Source code w/o comments None very large (weeks) Technology High High Reading technical documentation Source code with (good) comments Coding: weeks/months Writing: hours/days Large (days) Technology (maybe domain) Medium Depends Reading domain documentation Availability of (good) domain documentation Learning: years Writing: days Medium (hours) Domain (maybe technology) Medium Depends Reading introductory documentation Availability of (good) introductory documentation Writing: hours/days Maintenance: Minutes Small (Minutes) Business High Low Interview expert Knowledgeable expert willing to talk to you Learning: years Conversation: minutes Small (Minutes) all High High
  4. 4. Roles by viable information medium QAware 4 Manuals Presentations Documentation Code • End-Users • Operators/Admins • Senior Management • Market-facing staff • Product Owners • Requirements Engineers • UI/UX Designers • Architects • Developers
  5. 5. The truth is not (only) in the code QAware 5 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.
  6. 6. Cost and Benefit (1/2) QAware 6 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. []
  7. 7. 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 domain.
  8. 8. Cost and Benefit (2/2) QAware 8 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 better documentation. Inherent complexity, large size, or high quality requirements deemphasize coding as opposed to other activities, including documentation. 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.
  9. 9. Generating Code and/or Documentation When a specification is faithfully implemented, it turns into a documentation. 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) converge. 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
  10. 10. Don't add too many comments QAware 10 For writers, 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 maintenance. Don't say what the code does - the code already does that, and more concisely (getFoo gets value of Foo-field) For readers, a large number of comments amounts to a large amount of effort. 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",]
  11. 11. 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.
  12. 12. Advice for external documentation QAware 12 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 needed. 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.
  13. 13. Know your audience [Grady Booch: Object-Oriented Analysis and Design with Applications, Addison-Wesley, 1993]
  14. 14. Documentation is hard QAware 14 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 programming. 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.
  15. 15. Documentation is expensive Little faults will compound If you buy cheap, you buy twice. [wiseGeek,] [] RedAdair.jpgRedAdair.jpg BrokenWindowTheory
  16. 16. Documentation is no silver bullet QAware 16 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. []