Themen

Warum ist Dokumentation wichtig?

Vorurteile gegenüber Dokumentation

Arten von Dokumentation

Probleme mit (externer) Dokumentation

Folien

PDF

Glossar

PDF

• Grundlegende Ideen und Konzepte lassen sich schwer
  durch den Quellcode selbst dokumentieren.
• Dokumentiert werden sollte das „Was“ und „Warum“ (bzw. was warum nicht).
  Das „Wie“ beantwortet der Quellcode.
• Eine minimale externe Dokumentation (readme, install, erste Schritte)
  ist für größere Projekte unumgänglich.
• Einfach nutzbare Dokumentationswerkzeuge helfen,
  Dokumentation und Quellcode synchron zu halten.
• Externe Dokumentation ist essentieller Bestandteil von
  Software zur wissenschaftlichen Datenauswertung.

Diese Fragen dienen der persönlichen Beschäftigung mit der Thematik, werden aber nicht separat in der Vorlesung besprochen.

• Welche grundlegenden Fragen an ein Projekt sollte externe Dokumentation beantworten?
• Warum ist externe Dokumentation für ein Gesamtsystem zur wissenschaftlichen Datenverarbeitung und -Analyse von herausragender Bedeutung? Welche Kriterien sollte die einer solchen Dokumentation zugrundeliegende technische Lösung möglichst mitbringen?
• Welche Vorurteile werden häufig gegen Dokumentation vorgebracht und wie lassen sie sich entkräften?
• Welche Möglichkeiten gibt es, den Problemen externer Dokumentation (unvollständig, zeitaufwendig, asynchron zum Code) zu begegnen?
• Welche drei Aspekte sind wichtig im Umgang mit Dokumentation (und darüber hinaus mit vielen weiteren Aspekten des Programmierens)?

Eine kommentierte und handverlesene Liste mit weiterführender Literatur zum Thema. Die Auswahl ist zwangsläufig subjektiv.

Dokumentation ist der vielleicht am meisten vernachlässigte Aspekt vieler Open-Source-Projekte. Dafür gibt es aber auch eine ganze Reihe guter Quellen und Hinweise, wie man gute bzw. bessere Dokumentation schreiben kann:

• Write the Docs
  • Documentation Guide
  • A beginner's guide to writing documentation

• Writing Great Documentation
  Drei sehr lesenswerte Artikel aus dem Blog von Jacob Kaplan-Moss.
  • What to write
  • Technical style
  • You need an editor

Dass Dokumentation oft auf Englisch geschrieben wird, macht es für Nicht-Muttersprachler nicht einfacher. Ein zeitloser, kurz gefasster Ratgeber für die englische Sprache ist der Strunk & White [Strunk, 2000Strunk, William, Jr.; White, E. B. (2000): The Elements of Style, Longman, New York].

Für allgemeine Fragen und autoritative Antworten zur Schreibweise und Zeichensetzung der englischen Sprache sind das Oxford Style Manual [Ritter, 2012Ritter, Robert M. (Hg.) (2012): New Oxford Style Manual, Oxford University Press, Oxford, UK] für britisches und das Chicago Manual of Style [Chicago, 2010of Chicago, The University (Hg.) (2010): The Chicago Manual of Style, The University of Chicago Press, Chicago] für amerikanisches Englisch sehr empfohlen.

• of Chicago, The University (Hg.) (2010): The Chicago Manual of Style, The University of Chicago Press, Chicago
• Ritter, Robert M. (Hg.) (2012): New Oxford Style Manual, Oxford University Press, Oxford, UK
• Strunk, William, Jr.; White, E. B. (2000): The Elements of Style, Longman, New York

Die in der Vorlesung präsentierte Einteilung der Dokumentation im wissenschaftlichen Kontext, u.a. mit den theoretischen Abhandlungen (wie Abschlussarbeiten und Veröffentlichungen) stammt aus [Scopatz, 2015Scopatz, Anthony; Huff, Kathryn D. (2015): Effective Computation in Physics, O'Reilly, Sebastopol] (dort Kapitel 19). Dieses Buch verfolgt an vielen Stellen einen ähnlichen Ansatz wie die Vorlesung.

• Scopatz, Anthony; Huff, Kathryn D. (2015): Effective Computation in Physics, O'Reilly, Sebastopol

Der Essay „The Source Code Is the Design“ von Jack R. Reeves von 1992 ist im Anhang von Robert C. Martins Buch abgedruckt – und fand wohl erst dadurch eine weite Verbreitung. Das Buch selbst ist ebenfalls sehr lesenswert und behandelt Themen, die später in der Vorlesung noch detaillierter behandelt werden.

Der Artikel erschien ursprünglich unter dem Titel „What Is Software Design?“ im C++ Journal. Er findet sich online zusammen mit zwei weiteren Texten von Reeves bei developer.*:

http://www.developerdotstar.com/mag/articles/reeves_design_main.html

Dort kann man auch ein PDF-Dokument aller drei Essays herunterladen.

• Martin, Robert C. (2003): Agile Software Development. Principles, Patterns, and Practices, Prentice Hall, Upper Saddle River, New Jersey

Die Serie von Dilbert-Comicstreifen, die in der Vorlesung zu Beginn und am Ende gezeigt werden, um die Wichtigkeit des Themas zu zeigen, finden sich unter folgenden Webadressen:

• http://dilbert.com/strip/2010-02-27
• http://dilbert.com/strip/2010-03-01
• http://dilbert.com/strip/2010-03-02
• http://dilbert.com/strip/2010-03-03