Projektdokumentation

Hi,
die Frage ist eigentlich ganz einfach:
Wie macht ihr eure Projektdokumentation?
Für detaillierte Beschreibungen bieten sich natürlich die JavaDocs an. Aber für die Beschreibung der Architektur braucht man etwas anderes.
Nutzt ihr ein Wiki, Word, AsciiDoc, Papier, oder etwas ganz anderes?
Was für Tools verwendet ihr, um Sachverhalte wie bspw. Beziehungen zwischen Modulen zu visualisieren?

Ich biete meiste über AsciiDoc eine mitgelieferte Dokumentation an. Dabei orientiere ich mich meist an ARC42.

Ich verwende Libre-Office dazu (neben JavaDocs). In JavaDocs lassen sich zwar Querverweise einbinden, aber das macht diese schon wieder recht unübersichtlich. JavaDocs stellen für mich also nur eine kurze weniger detaillierte Mitteilung darüber dar, was in Methoden usw. geschieht.
In Libre-Office kann man solche Dinge dann auch noch visualisiert darstellen, das heisst anschaulich nicht nur mit Text, sondern auch mit Bildern. Darüber hinaus lässt sich mit Libre-Office dann auch aus einer Dokumentation heraus z.B. eine Projekt-Präsentation erstellen, wenn man es irgendwo vortragen möchte.

Allerdings hat dies auch einen Nachteil - JavaDocs fallen bei mir zunehmend spärlicher aus. Außerdem funktioniert dies bei Team-Projekten ganz und gar nicht.

Wir haben bei einem kleineren Projekt jetzt mal den Versuch gestartet, mit Markdown zu protokollieren (neben Javadoc). Vorteile sind für mich, dass die Dokumentation revisioniert mit der Software eingecheckt werden (und ein Pull Request ohne Doku abgelehnt werden) kann. Wir setzen intern Bitbucket ein, der kann die Dokumentation dann direkt im Browser rendern. Ein großer Nachteil ist für mich, dass man mit Markdown nur sehr schwierig größere Doku pflegen kann, da keine verschiedenen Abschnitte indiziert und verlinkt werden können.

Bei Kundenprojekten ist es ausschließlich “Word Dokument auf dem Sharepoint”, welches dann in der stressigen Zeit vor den Releases dermaßen vernachlässigt wird, dass es total unbrauchbar wird. Bei einem Projekt mussten sogar sämtliche existierenden Unit Tests mit Parametern und erwartetem Result in einer Excel Datei protokolliert und auf einem Verzeichnis abgelegt werden…

cd documentation
chmod -R 222

Mal sehen, wann es jemand merkt :smiley:

Die wenige „„realitätsnahe““ Erfahrung, die ich mit „„Dokumentation““ in diesem Sinne habe, beschränkt sich darauf: Es wird ein Word-Dokument erstellt, in dem haarklein aber so schwammig wie möglich beschrieben wird, was man vorhat. Wenn es zu wenige Seiten sind, wird noch ein bißchen JavaDoc/JSDoc-Output reinkopiert (der natürlich nie aktualisiert wird). Das ganze wird dann so lange für Reviews zirkuliert, bis jeder die Gelegenheit hatte, Engagement zu heucheln (d.h. irgendeinen unbedeutenden Firlefanz kommentieren, um den Verantwortlichen gegenüber den Eindruck zu erwecken, er hätte den ganzen Schlonz tatsächlich gelesen)

Auf Seite 384 muss es „Lorem ipsum…“ heißen, nicht „Larem ipsum…“ !!!111


Was „sinnvoll“ wäre (oder ich „sinnvoll“ finden würde) hängt aber stark von verschiedenen Faktoren ab

  • Ist das ein Internes Projekt?
  • Wie groß ist das Projekt?
  • Ist es ein Teilprojekt eines größeren Projekts? (Allgemein: Wie ist die Projektstruktur?)
  • Welche Projektlaufzeit gibt es?
  • Wichtig: Wer soll die Doku wann und mit welchem Ziel lesen? (D.h. z.B.: Geht es um eine Anwendung, die man startet und dann drin rumklickt? Oder um eine Library, die man (NUR) verwendet? Oder um eine Library, die irgendwann jemand weiterentwickeln soll? … )

Für ein externes Projekt, das irgendwann „beim Kunden abgegeben und dann vergessen“ wird, ist sowas wie ein Wiki wohl weniger geeignet. Da tut’s wohl ein Word-Dokument mit der High-Level-Übersicht für den Manager, und die JavaDocs für die Entwickler. Für interne Projekte könnte eine Kombination aus JavaDocs (ich bin ja JavaDoc-Nazi …) und vielleicht einer README.md sinnvoll sein, und/oder ggf. ein Wiki, wenn es länger laufen soll und öfter angepasst wird. (Auch wenn Wikis die Angewohnheit haben, nicht aktualisiert zu werden…)

Also, die übliche Antwort: „Kommt drauf an…“ :wink:

… leider ja. Später dazu mehr(*).

Frage: Habt ihr ein Ticketsystem, ergänzt dieses die Dokumentation? Optimalerweise steht dort, wer was wann wie dringlich usw. ZU TUN HAT!

(*): Dokumentation sollte eigentlich STÄNDIG aktualisiert werden - und auf dem NEUSTEN Stand gehalten werden. Leider ist das nicht praktikabel, weil man 3 Zeilen Code + JavaDoc schreibt, eine Commit-Nachricht, Konflikte behebt - und anschließend 30 Min. etwas in der Dokumentation ändert, wieder Konflikte behebt usw. Das ist aber alles unproduktiv, da Zweidrittel bis Dreiviertel der Zeit dann mit Dokumentation verprasst werden. :frowning:

Zur eigentlichen Frage: Entweder eine .txt, .md oder einfach ein Word Dokument.

arc42 kannte ich noch gar nicht. Das sieht auch auf den 2. Blick ganz interessant und brauchbar aus. Danke dafür!

Zum Thema AsciiDoc habe ich auch noch ein, zwei Fragen, die aber besser in einen separaten Thread passen.

Die ganzen Vorteile bietet AsciiDoc auch (wird mittels Plugin auch von Bitbucket Server unterstützt). Dort können aber auch Inhaltsverzeichnisse erstellt und Verlinkungen eingefügt werden. Einige größere OpenSource-Projekte setzen AsciiDoc für die Dokumentation ein.

Das bemerkt doch keiner, weil du nur auf deimen lokalen Repository arbeitest :wink: (Habe deinen Punkt schon verstanden :slight_smile: )

Sowas habe ich auch schon gesehen. Das stellt aber eher das untere Ende der Qualitätsfahnenstange dar, was definitiv nicht das Ziel sein sollte.

Ein Ticketsystem ist meiner Meinung nach selbst in kleinsten Teams essenziell. Für die Entwickler stellt es natürlich hochdetaillierte Dokumentation dar, vergleichbar mit den JavaDocs. Mir geht es hier aber eher um die makroskopische Sicht auf die Software, wie grundlegende Designentscheidungen.

Das ist auf jeden Fall gut zu wissen, ich werde es mir mal anschauen. Wenn auch die Wahl zu einem guten Teil auf Markdown gefallen ist, da so ziemlich jeder im Team es schon kannte, Ascii Doc hat sich nach bisherigem Stand noch keiner angeschaut.

Mal abgesehen von dem wie, WAS dokumentiert ihr eigentlich? Intern gilt bei uns, Designentscheidungen, API Benutzung, Webservices werden dokumentiert. Dann natürlich auch die technische Infrastruktur, Verknüpfung mit Elasticsearch, Datenbanken etc. pp. Bei Kunden war bisher jedes (!) mal gefordert, alle Klassen in einem Word File zu dokumentieren. Nicht nur alle Entities mit allen Feldern und Beschreibung, was jedes Feld tut (!!) sondern auch alle Controller Klassen, DAO, Eventhandler usw. Also all das, was man auch super mit Javadoc erschlagen kriegt (welches parallel auch gefordert war). Hält irgendjemand diese Detailtiefe für sinnvoll? Glaubt irgendjemand, dass sich so eine detaillierte Doku up to date halten lässt?

Tiefe und Aktualität schließen sich beide IMHO gegenseitig aus. Bedenkt mal, eine neues Projekt, was steht zunächst in der Dokumentation? Systemarchitektur und eine abstrakte Sicht auf das System. Bei der Nicht-TDD wird das dann alles nach und nach mehr. Fazit: Man kann die Doku nicht aktuell halten.

Aber für genau so etwas wurden doch ganze Bücher-Wälzer geschrieben.

Ehrlich gesagt: keine Chance

Aber manchmal, je nach SW/Projektart, steht es halt im Vertrag, dann mahct man halt etwas um so zu tun… siehe @Marco13 Ausfuehrungen.

In-House Cloud Software mit “Papier” zu dokumentieren ist IME Zeitverschwendung, JavaDoc/REST Doku nur fuer APIs die auch “extern” verwendet werden, schreibe keine Doku fuer den Kollegen neben dir.

Das könnte man mehr oder weniger wohlwollend interpretieren, aber so sehe ich das ziemlich kritisch. Würdest du zumindest zustimmen, wenn man sagt:

“Schreibe Doku für den Kollegen, der die Release Bugfixen muss, die natürlich zufällig genau in der Woche ist, wo du im Krankenhaus bist”

Oder

“Schreibe Doku für den Kollegen, der … deinen Job bekommt, nachdem du zum Manager aufgestiegen bist (weil du immer so effizient gearbeitet hast (weil du keine Zeit mit Doku verschwendet hast))”

?

Naja, es kommt schon auf den Kontext an :slight_smile:

Durch Pairing und PRs, generell die Idee dass man viel kommuniziert und dabei Wissen teilt haben eigentlich relativ viele einen Ueberblick was da so los ist.
Generell gibt es „Architekturrichtlinien“, d.h. viele „high level“ Konstrukte etc. wiederholen sich in verschiedenen Projekten sogar in unterschiedlichen Abteilungen immer und immer wieder.
Design dass davon abweicht bzw. speziell oder kontrovers ist, wird in „echten“ Meetings (die aber nicht laenger als 60 Minuten dauern) diskutiert und im Wiki festgehalten, oder nur per Wiki diskutiert, bei groesseren bzw. komplexeren Projekten wird verlangt dass theoretisch so ziemlich jeder im Team alleine weitermachen koennte wenn alle anderen ausfallen wuerden, theoretisch…
Es gilt „mehr kommunizieren, weniger schreibseln“…

„Bugfixes“ koennen IME in der Cloud anders gehandhabt werden als bei „normaler“ SW, das geht von abschalten des ganzen Features per Feature Flag, d.h. ohne Code Aenderungen/neue Releases sondern ein Dienst teilt der SW dynamisch zur Laufzeit mit „Feature A ist jetzt OFF fuer diese Instanzen“ bis zu Workarounds welche die „Site Reliability Engineers“ ausfuehren koennen (zB. fixen der Daten in der DB per SQL script etc.).
Das alles sollte irgendwann dazu fuehren das Bugfixes oft nicht sofort gemacht werden muessen

Dann gibt es da noch das Agile Mantra

heisst auf gut deutsch

:wink:

Manchmal findet man Perlen in (Legacy) Code Kommentaren von 2012 wie zB.

Man haben wir gelacht 2016 :smiley:

IME gehoert zum Manager nicht effizient entwickeln, sondern „soft skills“, also wissen wie man politisch agiert und manipuliert, toll redet bzw. Vortraege haelt, Fehlschlaege als Fortschritt verkauft usw., oft hab ich den Eindruck dass die technisch weniger begabten in eine Verwaltungsrolle „gefuehrt“ wurden…

1 Like

Natürlich ist eine direkte Kommunikation immer besser. Die grundlegende Architektur sollte aber irgendwo zu finden sein. Im Code sollte sich der Rest selbst erklären. Durch Einhaltung von Clean Code und TestDriven sollte das meiste klar sein.

@maki: stimmt, neben AsciiDoc dokumentiere ich vor allem die REST Services mit (meist) Swagger.

Feature-Toggles finde ich immer sehr interessant. Allerdings kosten diese auch immer etwas Aufwand. Das mache ich wirklich nur in seltenen Fällen.

Wie der Manager da sagen würde:

„We want both! (But it should not cost more: Software=Code+Documentation!!!)“

Und mit letzterem hätte er ja gar nicht mal so unrecht (und ich meine sogar, dass du das auch mal so geschrieben hättest, kann mich da aber auch täuschen). Immer wieder ist an verschiedenen Stellen (d.h. auch bei dir) von „Legacy-Code“ die Rede. Und was bedeutet „Legacy“? Ja, sowas wie „Hinterlassenschaft“ (oft (und bei Code fast immer) im Sinne von „Altlast“). Aber was bedeutet das? Ist das dann wieder so einfach wie „Schlecht+Alt=Legacy“? (insbesondere mit „Schlecht+Neu Legacy“?). Meiner Wahrnehmung nach nennt man „Legacy Code“ praktisch immer das, was jemand anderes vor einem geschrieben hat, und was man selbst (heute) ganz anders machen würde. Aber vielleicht hatte er dafür, dass er das so komisch gemacht hat, einen Grund. Wenn er den nur irgendwo aufgeschrieben hätte.

Hm.

(Nicht falsch verstehen: Doku ist kein „Heilmittel für schlechten Code“. Und ich weiß aus leidvoller Erfahrung, dass man da auch vollkommen falsche Prioritäten setzen kann. Ich hatte mal vorgeschlagen, im Abschlussbericht eines Projektes die Frage, warum bei dem Projekt so wenig rumkam, zu erklären mit einem einzigen Satz: „We wasted our time with writing documents instead of developing“ - nur um den fraktalen Witz zu provozieren, dass sie dann gefordert hätten, dass das ja vieeeel ausführlicher beschrieben werden muss :upside_down: )

Wie gesagt, kommt darauf an.
Hier interessiert sich kaum einer fuer Ausgiebige Doku als Word Doku, eigentlich keiner, in der letzten “Cloud” Firma genauso wenig.

Doku fuer REST APIs ist zwingend, JavaDoc fuer interne Java APIs ist gut, JavaDoc fuer alle public Java Methoden ist weder erwuenscht noch gemacht, die @since in Java APIs JavaDoc ist sogar verboten, da bin ich kein Fan von ehrlich gesagt…

Legacy = was in Prod lauft und nicht mehr einfach so geaendert werden kann weil es andere Parteien negativ beeinflussen wuerde.

@maki du sprichst mir oft einfach aus der Seele. :slight_smile:

1 Like