Themen

Warum ist Dokumentation wichtig?

Vorurteile gegenüber Dokumentation

Arten von Dokumentation

Probleme mit (externer) Dokumentation

Folien

PDF

Glossar

PDF

Video

MP4

Hinweis: Der Webcast wurde mit Tiny Webcasts for Lecture(r)s erstellt.

• 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

Ebenfalls sehr hilfreich ist der Beitrag How to maintain a successful open source project, der den Wert einer guten README-Datei hervorhebt und darüber hinaus eine Reihe weiterer sehr wertvoller Tipps gibt, wie man ein Open-Source-Projekt erfolgreich für alle Seiten gestaltet.

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.

Ein herausragendes Beispiel für gute Dokumentation und insgesamt gute wissenschaftliche Arbeit ist die Originalpublikation „Versuche über Pflanzen-Hybriden“ von Gregor Mendel aus dem Jahr 1866, die online im Volltext verfügbar ist. Eine unbedingte Leseempfehlung für jeden.

• 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

Für die Bedeutung und den Einfluss eines Wikis vgl. das Buch von Bo Leuf und Ward Cunningham [Leuf, 2001Leuf, Bo; Cunningham, Ward (2001): The Wiki Way. Quick Collaboration on the Web, Addison-Wesley, Upper Saddle River, NJ]. Letzterer war auch der Autor des ersten Wikis – lange vor dem Beginn von Wikipedia. Ein Buch, das sehr praxisnah die Nutzung von Wikis für die interne Zusammenarbeit in einer Organisation beschreibt, ist Wikipatterns von Stewart Mader [Mader, 2008Mader, Stewart (2008): Wikipatterns, Wiley Publishing, Inc., Indianapolis, IN].

• Leuf, Bo; Cunningham, Ward (2001): The Wiki Way. Quick Collaboration on the Web, Addison-Wesley, Upper Saddle River, NJ
• Mader, Stewart (2008): Wikipatterns, Wiley Publishing, Inc., Indianapolis, IN

Ein exzellentes Werkzeug für ganz unterschiedliche Bereiche einer Dokumentation, von der API-Dokumentation bis hin zum fertigen Nutzerhandbuch, ist Sphinx [Hasecke, 2019Hasecke, Jan Ulrich (2019): Software-Dokumentation mit Sphinx, hasecke.com, Solingen], das ursprünglich für die Dokumentation der Programmiersprache Python entwickelt wurde und über die Plattform Read the Docs weite Verbreitung erfahren hat.

• Hasecke, Jan Ulrich (2019): Software-Dokumentation mit Sphinx, hasecke.com, Solingen

Die Serie von Dilbert-Comicstreifen, die in der Vorlesung erwähnt 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