So, herzlich willkommen zum letzten Abschnitt. Software-Dokumentation.
Ich habe diesen Abschnitt zum Kapitel Wartung und Re-Engineering hinzugefügt.
Man hätte es natürlich auch beim Entwicklungsprozess haben können,
aber der vorrangige Zweck von Dokumentation ist ja das Verstehen.
Ist das Verstehen für Weiterentwicklung, Veränderungen, das, was wir unter Wartung ja verstehen.
Ja, die Verständlichkeit ist, dass eine große Problem,
die vorhanden sein und die Aktualität von Dokumentation des anderen große Problemen.
Und was ich Ihnen in diesem Abschnitt darstellen möchte, vermitteln möchte,
ist einige Empfehlungen, wie sie das in der täglichen Entwicklungspraxis erfolgreich integrieren können.
Wir starten mit den Zielen, ja,
Ziele bestehen ja darin, Kommunik zu kommunizieren,
Kommunikation vor allen Dingen mit den Kollegen,
Kommunikation in größeren Projekten und da geht es darum,
zunächst erst mal beim Software entwickeln, um ein gemeinsames Verständnis.
Alle Leute im Team müssen das Gleiche verstehen von denen,
was wir da tun, wie wir das tun.
Also vor allen Dingen die Software-Engineering-Konzepte seien es Entwurfsmuster seines Entwurfs,
Ideen, Architekturstile, grundlegende Einigungen über,
wie wir mit der Aufteilung der Fachlichkeit umgehen.
Das ist der eine Punkt, dieses Gemeinsame. Der zweite Punkt ist,
dass man mit Abstimmung zwischeneinander bessere Lösungen entwickelt, indem man über Lösungen diskutiert.
Und das kann man natürlich am besten dann tun, wenn man etwas vorliegen hat.
Das wäre nämlich das, wie man eine Lösung beschreibt.
Natürlich kann man auch über Ideen diskutieren, die man nur
im Kopf hat. Aber es ist sehr viel schlechter.
Am einfachsten ist das, wenn man irgendwas auch vor sich hat.
Und sei es nur etwas auf dem Bierdeckel oder einer Serviette.
Und natürlich wollen wir das Ganze langfristig haben.
Wir haben im Team, wird es immer Wechsel geben. Natürlich,
wenn man eine langholende Zeit beschreibt, sind es grundsätzlich andere Leute,
die nach zehn Jahren an einem Softwaresystem entwickeln, als die ursprüngliche Entwickler.
Aber wir wollen auch schon kurzfristig, es kommen neue Leute ins Team,
dann möchte man Wissen weitergeben und man möchte auch Erfahrungen weitergeben.
Positive, aber vor allen Dingen auch negative Erfahrungen.
Das ist erstmal zum Thema
gute Software
Und zum Thema langfristig, langlebige Systeme,
sie erinnern sich an das Stage Model, was uns zeigt,
wie wir, dass wir das geschäftskritische Systeme im Zustand evolutionäre Änderungen behalten wollen.
Dazu gehört es, dass wir Entscheidungen aufrechterhalten,
dass wir also dabei bleiben, was wir einmal entschieden haben.
Und dazu muss natürlich die Information weitergeben. Und dieses Wissen,
warum wir uns so entschieden haben, wie wir so entschieden haben,
ist auch das, was wir häufig wieder benötigen,
wenn wir Änderungen vornehmen.
Auf die lange Frist werden wir immer Änderungen haben und
Änderungen bezieht
Ziehen sich ganz häufig nur auf Änderungen der Ziele. Also wenn wir nachträglich,
zum Beispiel, wir haben über ein Grafik-Framework entschieden,
haben gesagt, ja, das nehmen wir,
das ist der beste Kompromiss zwischen Aufwand, Nutzen,
vorhandenen Kenntnissen, Möglichkeiten und Features und Mächtigkeit und dem Support.
Ja, und nach ein paar Jahren spielen plötzlich Lizenzkosten eine große Rolle.
Ja, und dann sind aber die anderen Punkte,
die wir damals als Entscheidungskriterium haben, sind alle noch interessant.
Das heißt, wir werden wieder Support-Leistungsfähigkeit,
Kenntnis im Team mit einfließen lassen.
Und deswegen ist das Wissen über die Entscheidungen und
die Grundlage von Entscheidungen
ganz wichtig
Außerdem, natürlich müssen wir langfristig die Grundkonzepte aufrechterhalten.
Ja, wir haben manchmal so Architekturbrüche, aber die sollten
nicht häufiger passieren, als sie denn unbedingt notwendig sind.
Das heißt, wir wollen bei den Grundkonzepten bleiben.
Und es sollte immer klar sein, wo sind Stellen vorgesehen für Änderungen.
Sie wissen alle, erkennen alle, diese alte Regel,
Jagnie, you won't need again.
Ja, das ist, sie werden das nicht wieder benötigen.
Man sollte nichts für die Zukunft entwickeln,
auch agile Entwicklungsmethoden sagen für jetzt und so einfach wie möglich.
Aber es gibt trotzdem noch ein paar Punkte,
wo wir über Änderungen schon nachgedacht haben
Das ist ein und ein weiterer Punkt ist,
auch auf die lange Frist, Dinge,
die wir erfolgreich entwickelt haben oder die wir für als erfolgreich kennengelernt haben,
die wollen wir weiter nutzen, wollen wir wiederverwenden,
weil wir woanders eine einsetzen.
Es gibt dieses Schlagwort, ich habe sie als Stempel drunter gemacht,
nachhaltige Entwicklung, das klingt so ein bisschen wie Queen Energy,
nachhaltig im Sinne von, wir wollen es lange nutzen mit geringem Aufwand.
Ja, und das ist eigentlich das wesentliche Ziel,
was wir hier unter dem Aspekt Reengineering und Wartung verfolgen,
wenn wir über Änderungen nachdenken.
Leider ist die Welt nicht so schön, dass Dokumentation
von Entwicklern nicht gern gemacht wird, ist oft geäußert.
Ich denke, es ist nicht das Problem,
das Gernemachens, sondern es ist das Problem der Priorität.
Und zwar möchte ich das mit einem sogenannten Dilemma, das Softwaredokumentation erläutern.
Ja, wir sehen hier zwei Kurven. Die eine Kurve,
die rote Kurve, wann haben wir denn Bedarf nach Wissen über Systeme.
Dieser Bedarf weg ist zu Anfang eher gering,
weil wir haben die Leute im Team,
die sich erinnern, ja, dieser Comic,
den wir hier ganz zu Anfang haben, der treibt das natürlich,
geh nochmal zurück,
Der ändert sich schon von letzter Woche nicht an,
die Sachen, die er gemacht hat.
Das wollen wir mal ein bisschen außen vor lassen. Ja,
wir hatten, wir haben ja hier eher so,
ja die Zeit, es steht ja keine Zeit dran,
aber ich würde jetzt eher denken, so nach einem halben Jahr,
nach einem Jahr beginnt der Bedarf zu steigen,
weil ich es nicht mehr genau weiß.
Oder nach fünf Jahren, weil die Entwickler nicht mehr da sind,
dann ist der Bedarf nach Informationen sehr viel höher.
Ja, so, aber zu dem Zeitpunkt,
wo ich das Wissen habe, also wenn ich zu diesem Zeitpunkt versuche,
das aufzuschreiben, habe ich kaum noch Wissen.
Ja, so, und zu dem Anfang,
als ich das, wenn ich das Wissen habe,
da ist aber gar kein Bedarf da
Da ist es immer wichtiger,
das neue Feature schnell laufen, zum Laufen zu bringen.
Ja, und dann hat auf jeden Fall die Dokumentation eine
niedrigere Priorität. Und ich wehre mich ganz entschieden dagegen,
das den Entwicklern anzulasten. Auch wenn man den Projektleiter fragt,
wenn sie kurz vor der Deadline sind und die Dokumentation ist
nicht fertig und da fehlen noch zwei, drei Features,
dann kann ich Ihnen ganz klar sagen, wie die Antwort aussieht.
Sie fragen ihn, soll ich lieber die Features machen oder
soll ich lieber die Dokumentation machen?
Da wird er Ihnen ganz klar sagen,
die Laufkirchigkeit und die Funktionalität der Software steht im Vordergrund.
Ja, und dann ist der Bedarf und deswegen die Priorität zu kriegen.
Dieses Dilemma, Das wird bleiben. Davon können wir,
und wir können nur versuchen, damit zu leben.
Ja, und was ich in diesem Abschnitt darstellen möchte, sind verschiedene Möglichkeiten.
Doch zunächst erstmal dazu, was brauchen wir überhaupt? Ich verwende hier eine Studie,
die wir im vergangenen Jahr bei der XI-Konferenz der führenden Konferenz,
International Conference und Software Engineering, steht auch hier ausgeschrieben,
hatten, dass es eine sehr hochrangige Konferenz mit einer enormen,
niedrigen Annahmenberater, also jeder ist glücklich, wenn er dort was unterbringt für den Forschern.
Und dieses Autoren-Team hat an untersucht, was brauchen die Leute am meisten.
Ja, wir sehen hier aus verschiedenen Phasen die verschiedenen Tätigkeiten,
die man macht und hier oben eine Reihe von Dokumentenartefakten,
die die Entwickler, die diese Autoren untersucht haben.
Da ist nicht alles dabei, was man sich vorstellen kann
und das Ganze hat den Charakter einer Heatmap, das heißt,
je intensiver die Darstellung hier die Gefärbung ist, desto stärker brauchen die das.
Diese, das, was wir hier sehen, beantwortet gleichzeitig
die Frage, Was sind stark benötigte Dokumentationsarten? So,
wenn wir uns jetzt anschauen, wo sind jetzt die ganz dunklen Farben,
wo sind die Sachen größer, 80 Prozent und wo sind die Sachen, die immerhin noch ziemlich stark eingefallen sind.
So sehen Sie für die erste Phase von Tätigkeiten,
Requirements und Design, Anforderungsanalyse und Entwurf, sehen wir,
ja, wir brauchen hier irgendwie,
es gibt so etwas, ein Dokument, Contribution Guideline,
Community Knowledge, das sind so eher die allgemeinen Informationen,
die der Entwickler nicht haben,
aber hier gibt es noch ein für Data-Base-Design noch ein Micration Guide für existierende Systeme,
wo ich die Daten übernehmen muss, ist das natürlich das Schlüsseldokument.
Ist aber nicht so häufig erwähnt worden,
es hat es nur irgendwie bis 60 Prozent geschafft.
Viel dunklerer Farben haben wir hier in der Phase Entwicklung und Tests,
und zwar für das Debugging, ganz klar,
da arbeitet man mit Code, das ist nicht überraschend,
dass die Code-Kommentare hier besonders stark sind für das Programmieren,
haben wir hier Contributian Guideline.
Ich nehme an, dass es sich um so eine Art
Entwurfsrichtlinien allgemeine Entwurfsrichtlinien eines Teams handelt. Bitte lesen Sie gerne
das nochmal nach. Dieses Paper habe ich auch Mudel,
so oft zum Nachlesen gestellt. Zusätzlich für die Programmierung FAQ,
das ist auf jeden Fall, sollte man die lesen,
denn manchmal werden die FAQs ja selten gelesen und für die APIs eine API-Referenz.
Das braucht man auf jeden Fall. Ja, für ist
die Bucking, haben wir hier noch auch noch dieses Community-Knowledge.
Für das Verstehen ist natürlich auch,
da arbeitet man mit und Co., ist nicht überraschend,
dass Code-Kommentare sehr wichtig sind, aber viele weitere Dokumente sind verstehen wichtig.
Und das ist ja ein Punkt, wo Evolution,
Software-Re-Engineering eine große Rolle spielen, also dieser Diese Entwurfsrichtlinien Compribution Nerds,
Community, Knowledge, das User Manual, obwohl es dann nur die fachliche Seite,
die Anforderungsseite, die Nutzerseite gibt, FAQ und Know-how-Tutorial.
Und wenn man Video-Tutorials findet, ist das auch noch eine gute Sache.
Ja, also das sind auch wichtige Punkte. Ja,
für Testen, Qualitätssicherung,
die Entwurfsrichtlinie nimmt man da zur Rate und hier relativ viel der anderen Dokumente,
Micration Guide, Release Notes, die immer sagen,
was passiert in jeder Version,
das How-to oder Installation Guide.
Das brauchen die Leute auch
Und in der Phase, wenn die Software schon im Einsatz ist,
Operations und Maintenance, haben die Autoren diese Phase hier genannt.
Daher sprach man vor allen Dingen die ganz dunklen Farben herrschen hier vor.
Bei Software Magration, das war ja ein Abschnitt in unserem Kapitel 4 auch.
Da geht es natürlich um Magration Guide klar. Das ist
ganz wichtig und Installation Guide spielt ja auch eine Rolle. Ja,
und dann haben wir noch, wenn man eine neue Technologie,
ein neues Framework kennenlernen muss, da gibt es noch FAQ und Videotutorials.
Soweit grundsätzlich hier nochmal die Hauptphasen und die die Hauptdokumente,
also am meisten wird das hier das Development in Testing im Development in Testing,
haben wir die meisten, den meisten Bedarf nach Dokumentation der verschiedenen Arten.
Man könne die Studie jetzt ein bisschen anders führen,
wenn man noch ein paar andere Dokumente macht,
aber im Prinzip überrascht uns das ja vermutlich nicht,
jedenfalls nicht die unter ihnen, die schon in größeren Projekten mitgearbeitet haben.
Ja, es gibt großen Bedarf nach Dokumenten und das ist nicht überall gleich,
nicht in jeder Phase, es ist gleich und hier sind ein paar herausgehoben.
Als Antwort auch diese Prüfungsfrage sollten Sie auf jeden Fall sagen können,
was hier, dass wir bei Programm Contraintion Und bei Debucking,
die Code-Dokumente vor allen Dingen brauchen und bei Entwurf,
also gerade diese Contribution-Guideline und Community-Knowledge,
die brauchen wir halt hier im Entwurf, Tätigkeiten,
aber auch beim Feindesign, bei der Programmierung brauchen wir das.
Und die fragen natürlich,
die mit Installationentest und so weiter zu tun haben,
dann eben vor allen Dingen bei Qualitätsmanagement hier oder auch,
wenn wir Release-Management haben, haben wir diese Dinge.
Soweit, das sind die Dokumente, die benötigt werden.
Und wir haben, wenn wir versuchen,
Probleme zu lösen, sollten wir auch wissen,
worin bestehen die Probleme
Das ist die nächste Frage in unserer Fragenliste. Ja,
welche Frage 2, welche Probleme beeinträchtigen die Nutzbarkeit von Dokumentation?
Und da habe ich aus dem gleichen Paper,
ich habe ja nur die Kurzbezeichnung,
das gleiche Paper sagt auch etwas zu dem untersucht auch,
welche Probleme vor allen Dingen bestehen.
Ja, und da gibt es zunächst erstmal,
die haben das in drei Themenblöcke gegliedert, zunächst erstmal,
wie sie das bezüglich Informationsgehalt aus und dieser Informationsgehalt ist vor allen Dingen das Problem,
dass die Dokumentation ganz häufig nicht aktuell ist.
Das ist ein großer, wichtiger Punkt,
dass die Dokumentation nicht vollständig ist oder dass man sich
jedenfalls nicht darauf verlassen kann, dass sie vollständig ist.
Und dass sie nicht immer korrekt ist und alles abdeckt.
Das ist ein ganz wichtiger Punkt. Für die Form,
in welcher Art liegt das denn vor? Ist es besonders ein besonderes Problem,
besondere Herausforderung, dass die Wartbarkeit, jetzt nicht Wartbarkeit von Software,
so ein Änderungsaufwand für Dokumentation schwer gemacht wird dadurch,
dass wir überflüssige Informationen haben, Sachen,
die man eigentlich nicht wirklich braucht.
Manche Sachen sind dupliziert drin. Ja, wir wollen alle,
dass es ein bisschen Verdundanz gibt, dann besteht man besser,
aber wenn es dann an verschiedenen Stellen unterschiedlich dasteht.
Ja, das hat dann wieder was mit korrekter,
durchaus auch zu tun, dann macht es das Überarbeiten schwierig.
Wenn Sie sich vorstellen,
so ein riesengroßes Wiki und das kommt auf verschiedenen Seiten vor,
versuchen Sie mal, das konsistent zu halten.
Ganz schwierig. Und das ist eben deswegen ein Problem der Wartbarkeit.
Ja, Lesbarkeit, insbesondere Klarheit, klarer Verständlichkeit,
die Informationen, so wie wir sie brauchen.
Das ist doch ein großes Thema. Und wir wollen uns
danach orientieren, was braucht denn der Entwickler?
Was braucht der Anwender einer API
Und natürlich die Nützlichkeit, da spielt hinein,
dass wir die Informationen haben, die wir wirklich brauchen,
dass wir sie in der Form haben, dass wir sie gut verstehen.
Von Vokubular her, von der Aufbereitung zum Beispiel eine Grafik,
sagt mehr als tausend Worte.
Ja, so kennen, das kennen sie.
Und das spielt hier eine ganz große Rolle. Und der dritte,
der dritte Komplex, den wir hier haben,
sind die Frage des Entwicklungsprozesses, wie wirkt sich das,
wie ist das im Prozess eingeordnet,
was sind dafür wiederum nur Probleme genannt und
wie sieht das aus mit den Werkzeugen
Als wichtigster Punkt nannten die hier bei dieser Studie Befragten die fehlende Zeit.
Das hat mit der Priorität zu tun, über die ich gerade gesprochen habe.
Ja, Dokumentation hat ganz häufig zum Zeitpunkt,
wenn das Wissen da ist, eine niedrige Priorität.
Und deswegen bekommt sie auch wenig Zeit. Und deswegen ist die Dokumentation,
tatsächlich leidet sie unter fehlender Zeit. Der nächste Punkt ist,
betrifft die Aktualität, die wir hier vorne schon bemerkt haben,
wenn wir Fehler in der Dokumentation haben,
diese Fehler zu beheben, inkonsistenten zu beheben.
Das passiert selten, zu selten,
weil es einfach nicht eingebunden ist in den Entwicklungen
Entwicklungsprozess. Ich habe zwar eine Kotabnahme, aber keine Abnahme der Dokumentation,
einfach weil die Dokumentation zu dem Zeitpunkt jedenfalls eine niedere Priorität habe.
Ebenfalls wurde als wichtiger Punkt genannt, schlechte Organisationen der Dokumente,
dass ich also nicht das finde,
was ich brauche oder wichtige Inhalte fehlen,
nur oberflächliche Inhalte da sind oder nicht die angemessene Detail tief.
Und was auch noch genannt wird,
und darauf möchte ich ganz besonders hinweisen, Querbezüge.
Das ist das Wichtige, die Referenzen,
nenne ich das jetzt hier mal,
das ist einer der ganz,
ganz wichtigen Punkte
Ich habe hier auf dieser Folie nur die wichtigsten Sachen zusammengefasst,
die volle Übersicht finden Sie, wie gesagt,
in dieser Quelle, wenn Sie die Zeit haben und das Interesse,
schauen Sie da gerne mal rein.
Ich möchte aber noch auf einen Punkt extra hinweisen,
und zwar ein ganz grundsätzliches Problem, was hier,
was vielen der anderen Punkte irgendwie mit hervorsteht,
nämlich die Frage, dass wir das Warum brauchen.
Ganz viele Dokumentationen enthalten Informationen, wie etwas gebaut ist.
Aber ganz selten, warum? Ja,
und das ist es wert, uns hier zu schreiben
Musik Warum ist es so? Warum ist es so gebaut,
wenn sie so wollen, statt? So, und das
machen wir auch mal rot hier. Also das ist die Kernfrage,
die hier bei der Nützlichkeit steht, die bei dem steht,
wo wir das, was wir brauchen,
die bei den Querbezügen, bei den Referenzen steht,
es ist besonders wichtig für das Verstehen des Warum,
wenn wir wissen, wozu gehört es?
Gehört es, zu welchen Anforderungen gehört es,
zu welchen Testfällen gehört es, zu welchen Vor- und Nachbedingungen gehört es?
Ja, das sind ganz wichtige Punkte und deswegen möchte ich
das noch hier zusätzlich hervorheben. Soweit also zu den Fragen,
die wir bei den Zielen haben. Ja,
also das war die Frage 1 und die Frage 2,
die wir hier haben