Eigentlich wollte ich diesen Text Dokumentation von Code nennen, mir ist aber beim Schreiben aufgefallen, dass dieses Thema viel grösser ist.
Mich wurmt das Thema Dokumentation schon seit meines Studiums. Wir haben viel von Projektorganisationstechniken, wie Agile, Wasserfall oder V-Modell gelernt. Wir haben DevOps in einer Tiefe besprochen, dass es einem schon wieder an den Ohren auslief. Aber das Thema Dokumentation wurde immer nur sehr holzschnittartig betrachtet.
Jedes Mal, wenn es zur Sprache kam, wurde nur auf Softwaresysteme, wie JavaDoc, Doxygen und PHPdoc verwiesen. Damit dokumentiert man Code. Nicht zu viel, damit nicht bei jeder Änderung die Dokumentation angepasst werden muss und nicht zu wenig, sodass es praktisch nutzlos für das Verständnis wird. Für den „Rest“ gibt es UML, einen Standard der sehr präzise ist, aber derartig wenig Freiraum lässt, dass ich praktisch niemanden kenne, der ihn Standardkonform verwendet. Klassendiagramme sind dabei mein Lieblingskonstrukt, sie werden sehr schnell unübersichtlich ab einer gewissen Projektgröße, sodass man sich durch verschiedene Ebenen der Abstraktion bewegt, man aber ohne wochenlange Einarbeitung an der geistigen Speicherkapazität scheitert, wenn man in der dritten Ebene angekommen ist und nicht mehr weiß, was man ursprünglich suchte.
Ein Drama in mehr als 40 Wörtern.
Eine großangelegte Umfrage zu Open Source zeigt, dass unvollständige oder verwirrende Dokumentation zu den Hauptproblemen freier Software zählt [1]. Das gilt neben Anwendungsdokumentation insbesondere auch für technische Dokumentation, etwa von Softwarearchitektur. Diese Aussage können wir sicherlich verallgemeinern: schlechte Dokumentation von Software erschwert Änderung, Support und letztlich auch Nutzung. Wir möchten hier auf technische Dokumentation von Software abzielen, also beispielsweise Entwicklungs-, Architektur- und Betriebsdokumentation. Das Thema Anwendungsdokumentation klammern wir bewusst aus.
Unserer Erfahrung nach behindern eine ganze Reihe von Faktoren die Erstellung und kontinuierliche Pflege technischer Dokumentation:
- Ungeeignete Werkzeuge, die ursprünglich nicht für die Erstellung und Pflege solcher Dokumentation gedacht waren.
- Geringe Motivation seitens der Entwicklungsteams, oftmals verstärkt durch die oben genannten Defizite der entsprechenden Werkzeuge.
- Unklare Vorstellung über Struktur, Form und Inhalt von Dokumentation: Entwicklungsteams haben keine klare Vorstellung davon, was und wie sie dokumentieren sollen.
- Schlechte Vorlagen ("Templates") für Dokumentation.
Kam immer wieder von Neuem an die Spitze: Der Musiker und Produzent Nile Rodgers. Nach Erfolgen mit seiner Band CHIC produzierte er Songs für Diana Ross, Michael Jackson, Madonna oder Daft Punk und Eric Clapton. ARTE widmet ihm ein Porträt und im Anschluss ein Konzert mit seinen besten Hits.
Der Musikproduzent Nile Rodgers wurde 1952 in einem armen Stadtteil von New York geboren. Seine Karriere begann in der Band der "Sesamstraße", später spielte er für die Hausband des legendären Apollo Theater in Harlem. Eine herausragende Begabung, aber auch harte Arbeit, Menschlichkeit und Fairness verhalfen ihm zu seinem großen Erfolg im Musikgeschäft.Musiker wie Madonna, David Bowie, Diana Ross, Michael Jackson, David Guetta, Daft Punk und viele andere vertrauten dem "Hitmaker", der ihrer Karriere entscheidende Impulse gab. Der Schlüssel zu seinem Erfolg ist wohl, dass Nile Rodgers es perfekt versteht, sich an den persönlichen Musikstil jedes Künstlers anzupassen. Die Dokumentation betrachtet Nile Rodgers‘ unkonventionelles Schaffen und wirft mit Hilfe von Archivbildern, Clips, Anekdoten und exklusiven Beiträgen von Zeitgenossen einen Blick hinter die Kulissen seiner Tätigkeit als erfolgreicher Produzent der Superstars.
Dokumentation von Marjory Déjardin (F 2015, 52 Min)
Immer wieder faszinierend wenn sich das Auto nach dem Anlassen langsam erhebt, bis es seine endgültige Reisehöhe erreicht hat. In einer DS schwebt man geradezu über die Straße.
Ein Auto, das mehr war als ein Fortbewegungsmittel - die Ente. Unter diesem Kosenamen ist der Kleinwagen in Deutschland besser bekannt als unter 2CV, der offiziellen Modell-Bezeichnung von Citroen.
Entwickelt wurde der 2CV jedoch für die französische Landbevölkerung. Billig, sparsam, robust, das Aussehen dagegen spielt keinerlei Rolle. Das ganz kleine Auto sollte schlechte Wegstrecken bewältigen und 4 Personen sowie einen Zentner Kartoffeln transportieren können, und das mit einer Geschwindigkeit von 60 km/h. Außerdem solle das Fahrzeug so gut gefedert sein, dass ein Korb Eier eine Fahrt über holprige Feldwege unbeschadet übersteht. Die sagenhaft weiche Federung war eines der Ergebnisse dieser Vorgaben.
Der kleine 2-Zylinder, der knatterte wie ein Sportflugzeug, wurde in Deutschland vor allem in den 6ger und 70er Jahren von jungen Leuten gefahren, von Studenten, Intellektuellen, Individualisten. Die Ente war das Status-Symbol eines alternativen Lebensstils. Das wird auch auf Treffen von Entenfahrern deutlich: Keine Ente gleicht der anderen.
Der kleine 2CV :kaum ein Auto wurde länger gebaut, das Aussehen dabei nur wenig verändert. Der Motor dagegen, auch das ungewöhnlich, wurde im Laufe der Bauzeit dreimal so stark. Von 9 PS auf it 29 PS , von 65 km/h Spitze auf immerhin 115 km/h.
In den 70er Jahren war der 2CV das erfolgreichste Modell von Citroen. 1990 wurde die Produktion eingestellt - über 5 Millionen Mal war die Ente einschließlich der Kastenvariante gebaut worden.
Was macht Hunde aggressiv und wie kann es sein, dass Kampfhunde immer wieder zur Gefahr werden? "Die Story im Ersten" sucht Antworten auf diese hitzig diskutierten Fragen.
Um dir sowohl den Einstieg als auch die weiteren Schritte zu erleichtern, haben wir in unserem Wiki umfangreiches Dokumentationsmaterial für dich gesammelt und aufbereitet. Wir freuen uns, dass du dich hier umschaust! Am linken Rand findest du eine Übersicht über die wichtigsten Themen. Rechts oben auf der Seite steht dir eine Volltextsuche bereit, wenn du nicht genau weißt, wo du etwas Passendes finden könntest.
Du schaust öfter hier rein und möchtest nur wissen, was es Neues gibt? Dann schau dir die aktuellen Änderungen an.
Du bist noch blutiger Anfänger und weißt gar nicht so recht, wo du anfangen sollst? Dann helfen dir vielleicht diese Einstiegsfragen fürs erste weiter:
Die Diskussion ist fast so alt wie die IT: Wie viel Dokumentation benötigt ein System? Während es für den Kunden oft nicht genug sein kann, möchte der typische Entwickler am liebsten ausschließlich Code erzeugen. Eine leicht falsch interpretierbare Aussage aus dem Agilen Manifest zum Thema Dokumentation hat die Diskussion noch weiter aufgeheizt. Guter Rat scheint teuer. Aber so schwierig ist es letztlich gar nicht und ein wenig Systematik bei den Dokumentationsarten sowie gerade die agilen Prinzipien helfen, Inhalt und Umfang einer guten Systemdokumentation zu optimieren. In diesem Artikel werden zwei einfache Werkzeuge vorgestellt, die helfen, Dokumentation nicht mehr auf “Verdacht” zu erstellen, sondern zielgerichtet nach Sinn und Wert zu optimieren.