Empfohlen
Empfohlen
Weitere ähnliche Inhalte
Ähnlich wie Dokumentation in agilen Projekten - WebMontag Edition
Ähnlich wie Dokumentation in agilen Projekten - WebMontag Edition (20)
Dokumentation in agilen Projekten - WebMontag Edition
- 7. aber warum?
- 8. –Robert Bruckbauer „Eine User-Story kann Wissen zwar sehr effizient vermitteln, aber das Wissen wird nicht in einer nachhaltigen Form gespeichert.“
- 9. Agil hat die Art wie wir Entwickeln zum positiven verändert.
- 10. Dann lasst uns auch Dokumentation bedarfsgerecht machen.
- 11. Was wollen wir eigentlich Dokumentieren?
- 12. Produktdokumentation • Fokus auf das Softwareprodukt • Alle Dokumente für Betrieb und Nutzung der Software • Anforderung an Umfang und Format durch Auftraggeber
- 13. Systemdokumentation • Fokus auf das Softwareprodukt - aber Innensicht • Beschreibt, wie die Software funktioniert • Hilft bei Entwicklung und Weiterentwicklung der Software
- 14. Projektdokumentation • Fokus auf das Projekt • Dokumentiert und Unterstützt Projektfortschritt • Liegt in der Verantwortung des Teams
- 15. Prozessdokumentation • Wie gehen wir im Projekt vor • Welche Prozesse liegen dem Projekt zugrunde
- 16. Und wie kriegen wir das alles Bedarfsgerecht?
- 18. Ist das Dokument für diesen Leserkreis geeignet?
- 19. Ist die Detailtiefe für den Leserkreis geeignet?
- 20. Bietet das Dokument dem Leserkreis den gewünschten Nutzen?
- 21. Wer hätte einen Nachteil, wenn wir das Dokument nicht schreiben?
- 22. Ein Dokument das keiner ließt brauche ich nicht schreiben.
- 23. Was lohnt es sich aufzuschreiben?
- 24. „Dokumentation ist wie guter Rotwein, der Wert steigt mit der Zeit…“
- 27. Motivation, Begründung und Alternativen von Entscheidungen
- 29. Tools ≠ Lösung
- 30. Word, Confluence, Jira, Excel, JavaDoc, md, HTML, LaTex, AsciiDoc?
- 31. Nutze was für dein Team passt. Aber nutzt wenige Tools, mit denen alle arbeiten können.
- 33. Wiki-Systeme Für Projekt und Systemdokumentation • Teamwork bei der Erstellung • Struktur durch Verlinkung • Formatierung • Ablage von Dokumenten/Bildern/Diagrammen • Suchfunktion • Änderungshistorie / Versionsvergleich
- 37. anhängig vom Thema… aber eigentlich immer
- 41. Anforderungen müssen erst zu dem Zeitpunkt beschrieben sein, zu dem die Implementierung der Funktionalität begonnen wird.
- 42. Aber das BIG PICTURE muss allen am Anfang des Projektes klar sein.
- 43. Wie verhindere ich das ich den richtigen Zeitpunkt verpasse?
- 44. Die Erstellung von Dokumenten fließt als Arbeitspaket mit in die Sprints ein.
- 45. Dokumentationsaufgabe • Welcher Vorraussetzungen müssen erfüllt sein um die Aufgabe umzusetzen? • Welcher Aufwand ist nötig / gerechtfertigt? • Wer kann die Aufgabe übernehmen? • Welche Priorität hat diese Aufgabe im Vergleich mit anderen Aufgaben? • Bis wann soll die Aufgabe abgeschlossen sein?
- 46. Dokumente, werden wie Software inkrementell erstellt.
- 47. Dokumentations-Inkrement • Sukzessive Erweiterung der Dokumentation • Passend zur Software werden neue Kapitel ergänzt • Bei Bedarf werden bestehende Kapitel aktualisiert
- 49. Clean Code Developers = Clean Doc Developers?
- 50. Wir schreiben Text für Dokumente und Epics bzw. Stories in der Sprache unseres Kunden, wie wir "Programmtexte" in Sprachen schreiben, die Computersysteme verstehen.
- 51. Wir wenden das Prinzip "Keep it simple, stupid" der Programmierer an, damit Inhalte im Wiki nicht zu schnell verderben.
- 52. Wir wenden das Prinzip "Don´t Repeat Yourself" (DRY) der Programmierer an, um die Inhalte im Wiki weitestgehend frei von Redundanzen zu halten.
- 53. Wir wenden die Pfadfinderregel an und führen Reviews durch, um die Qualität unserer Dokumentation laufend zu verbessern.
- 54. Wir nutzen das Prinzip "Separation of Concerns" (SoC), indem wir fachliche und technische Belange klar von einander trennen.
- 55. Genauso wichtig wie "Source Code Conventions" für Code, sind die Regeln und Vorlagen zur Erstellung von Inhalten im Wiki. Wir definieren klare Regeln für den Aufbau jedes Artefaktes. Wir unterstützen die Autoren durch Vorlagen für jedes Artefakt. Handbücher unterliegen teilweise noch strengeren Richtlinien.
- 56. Das Prinzip des "Single Level of Abstraction" (SLA) fördert wie bei Code die Lesbarkeit von Inhalten im Wiki. Autoren können sich auf eine konkrete Aufgabenstellung konzentrieren. Reviewer können Inhalte effizienter prüfen.
- 57. Was sollte ich mir bis jetzt gemerkt haben?
- 58. BIG PICTURE
- 60. Nachvollziehbar!
- 62. Beipackzettel
- 63. Ein Diagramm sagt mehr als tausend Worte
- 64. Tabellen können Informationen systematisch und übersichtlich Präsentieren Beispielsweise Key-Value Paare Vor und Nachteile Produktvergleic he Abfolgen von Handlungen aber sie sind kein Ersatz für Fließtext helfen aber in vielen Fällen
- 65. DOAD
- 66. Definition of agile Documentation • Wir sichern Wissen auf lange Zeit mit hoher Qualität. • Wir beschränken uns auf das Wesentliche und Notwendige. • Wir dokumentieren die Ergebnisse von Diskussionen. • Wir vermeiden persönliche Arbeitsunterlagen! • Wir definieren Grenzen: Was muss sein, was brauchen wir nicht. • Wir unterscheiden flüchtige und dauerhafte Informationen.
- 67. Definition of agile Documentation • Wir vermitteln ein "Big Picture" für alle Zielgruppen. • Wir etablieren eine gemeinsame Sprache im Projekt. • Wir pflegen von Anfang an ein Glossar. • Wir pflegen externe Quellen in einer Linksammlung. • Wir legen einen allen im Team bekannten Weg zum Erfassen von Inhalten fest.
- 68. Definition of agile Documentation • Jede Information ist dort, wo sie sein soll – und nur dort! • Wir verbessern uns laufend. • Wir sind flexibel bei Änderungen an der Vision des Produktes. • Wir zerlegen die Aufgaben im Projekt in "handliche Portionen". • Wir sind robust im Zusammenhang mit nicht- funktionalen Anforderungen.
- 69. Literaturtipps und Quellen • Dokumentation in agilen Projekten - Andreas Rüping • Agile Dokumentation für Stakeholder und Projektmitarbeiter - Robert Bruckbauer • http://agilere.org/
Hinweis der Redaktion
- Die letzte Session am Abend und dann auch noch mit Dokumentation im Titel - und ihr seid trotzdem hie geblieben. Danke
- Funktionierende Software mehr als umfassende Dokumentation. Viele Entwickler lesen das und..
- Die Party geht los. Coders gone Code. Endlich wieder nur Softwareentwickler statt Tippse. Und dieser Gedanke hat sich auch bei vielen Festgesetzt. Agil braucht keine Dokumentation Schaut man sich das Agile Manifest genauer an steht da am Ende noch ein Satz.
- Hmm. Die Werte auf der rechten Seite sind also auch wichtig und gehören dazu.
- Die Party geht los. Coders gone Code. Endlich wieder nur Softwareentwickler statt Tippse. Warum finden das alle so großartig. Entwicklung in den 90ern hieß oft. Schwergewichtig. Lange Zyklen. Die Rechner waren langsamer. Bauen und kompilieren - Time 4 Coffee Und dieser Gedanke hat sich auch bei vielen Festgesetzt. Agil braucht keine Dokumentation Schaut man sich das Agile Manifest genauer an steht da am Ende noch ein Satz.
- Agil ist doch 1 zu 1 und direkt Fragen klären. UND wir haben User Stories
- Warum ist das so. Beim arbeiten mit einem physischen ScrumBoard steht am ende ein Mülleimer und da wandern die Zettel rein.
- Die Teams tauschen untereinander Wissen aus Wir erkennen Probleme und Missstände viel schneller Wir sind in der Lage auf Veränderungen zu reagieren und können Bedarfsgerechte Software entwicklen.
- Wir werden uns anhand von Fragen durch die Themengebiete der agilen Dokumentation tasten.
- Was gibt es alles für Dokumentationstypen in Softwareprojekten - auch in agilen.
- Produktdokumentation ist, wie der Name schon sagt ein Teil des Produktes. In Kunden Projekten ist Format und Inhalt oft vorgegeben und die Lieferung ist Teil des Vertrags. Nutzungshandbuch, Installationshandbuch, Betriebshandbuch, Servicehandbuch und z.B. Online-Hilfe Auch für unsere eigenen Produkte wie ProjectForge, Baumeister etc. gibt es diese Dokumente, in von uns gewählter Form
- Architekturentscheidung, Code Kommentare, Softwaredesign, Datenmodell Hier ist das Team im Fokus und auch die Form der Dokumentation liegt meist in unserer Hand.
- UserStories, Backlog, Epic Jira und das Team Confluence sind alles Teil der Projektdokumentation. Glossar, Use-Cases, Testfälle, Leistungsbeschreibung Hier ist klar was das Projekt macht.
- Die Prozessdokumentation beschriebt wie das Team etwas macht. DOR und DOD. Arbeitsweisen Richtlinien Freigaben und Workflows. Workflow mit GIT, Jenkins unsw.- Wann wird ein Branch erstellt etc. alles Teil der Prozessdokumentation
- Das ist ja doch ganz schön viel an Dokumentation. Fang und frag dich..
- Als erstes schauen wir - Wer ist der Leserkreis dieses Dokumentes. Und wenn es nicht jetzt gelesen wird, Wer wird es vielleicht in Zukunft lesen.
- Der Fachbereich braucht andere Information als die IT. Ein Entwickler braucht andere Informationen als ein Supportmitarbeiter der Hotline
- Details können den Nutzer erschlagen oder das Dokument für die Arbeit erst hilfreich machen.
- Manchmal ist der Nutzen auch nur das „haben, weil es der Prozess erfordert.“ Und ganz wichtig.
- Wenn wir diese Fragen nicht genau Beantworten können, sollten wir über das Dokument nochmal nachdenken. Denn
- Es sei den es ist Teil meiner Beauftragung und ich werde dafür bezahlt. Aber auch dann kann ich bei der Detailtiefe und dem Aufwand genau schauen das er im Rahmen bleibt.
- Alles was heute oder morgen einen Nutzen hat.
- .. und von zu viel bekommt man einen dicken Kopf.
- Wir entwickeln und betreiben Projekte mit unseren Partnern und Kunden die oft einen langen Lebenszyklus haben und über einen langen Zeitraum weiterentwickelt werden. Das was ich heute gut Dokumentiere hat vielleicht erst einen Wert, wenn ich selbst schon nicht mehr im Team bin. Also was lohnt sich immer?
- Auch über die Funktion einzelner Features - Erlaubt auch nach Monaten und Jahren einen schnellen Zugang zum Projekt und erleichtert den Einstieg.
- Warum haben wir das damals so gemacht? Was wären unsere Alternativen Überlegungen? Fachliche und technische Architektur können Auge zu Auge besprochen werden - aber das Ergebnis muss für die Nachwelt dokumentiert werden
- Mit welchen Tools dokumentier ich am besten?
- Ein Tool kann dich unterstützen, aber kann nicht die Arbeit für dich erledigen.
- Wir können heute aus einer Vielzahl von Tools auswählen und wenn wir über den Zaun schauen finden wir da draußen auch Tools bei denen das Gras noch viel Grüner ist und wo der Kerl im YouTube Video eigentlich gar nichts mehr macht und es kommt eine super Dokumentation raus. Aber ein Ferrari ohne Fahrer ist das gleiche Verkehrshindernis wie ein Golf ohne Fahrer. Wichtig ist das Ihr damit arbeitet.
- Als Faustregel für die Bewertung gilt:
- Als kleiner Praxistipp: Nutzt Confluence - und nutzt die Möglichkeiten von Confluence
- Warum? Schauen wir wieder ins agile Manifest.
- Dafür haben die Definition of Ready als Quality Gate für den Einzug einer Anforderungen in den Sprint. Die wir als Teil der Prozessdokumenttation erstellt haben bevor Sie gebraucht wird. Um mit der Implementierung zu beginnen muss die Anforderung bewertet und der DOR entsprechen.
- Die Produktvision steht am Anfang der Entwicklung und sollte auch allen im Team klar sein. Nur so sind alle im Team in der Lage auch Feedback auf Anforderungen zu geben, die evtl. diese Vision nicht unterstützten - Stichwort Bedarfsgerecht.
- Bei den einzelnen Aufgaben ist das klar - die müssen ja zur Entwicklung den Sprung vom Backlog ins Speintlog schaffen. Aber wie ist das z.B. mit der Produktdokumentation
- Und wenn ich eine Dokumentation als Arbeitspaket plane stellen sich einige Fragen.
- Folie lesen Und wir sind ja Agil - also ..
- Wer zu lange wartet mit der Dokumentation wird am Ende von einer Welle überrollt.
- Lasst uns mal schauen, welche Werte und Prinzipien der Clean Code Bewegung wir für Dokumentation nutzen und adaptieren können.
- Dabei hilft z.B. ein Glossar für ein einheitliches Verständnis
- Wer mehr tut als das Einfachste, lässt den Kunden warten und macht die Lösung unnötig kompliziert. und erschwert die spätere Änderung
- Jede Doppelung von Code oder auch nur Handgriffen leistet Inkonsistenzen und Fehlern Vorschub. Das Prinzip motiviert uns auch, Stichworte und Begriffsdefinitionen in einem Glossar zu verwenden.
- Wer kennt die Pfadfinderregel? Hinterlasse den Rastplatz immer sauberer als er bei deiner Ankunft war.
- Wenn eine Codeeinheit keine klare Aufgabe hat ist es schwer sie zu verstehen, sie anzuwenden und sie ggf. zu korrigieren oder zu erweitern. Epic, und User Story dienen ausschließlich der fachlichen Beschreibung. Layouts verwenden wir nur für die Spezifikation der Benutzeroberfläche (Zielgruppe Entwickler). Das Benutzerhandbuch (Zielgruppen Tester und User) verwenden wir nur für die Beschreibung der Verwendung der Benutzeroberfläche. Das Betriebshandbuch (Zielgruppen Tester und Operatoren) nutzen wir nur für die technischen Aspekte der Software.
- Code wird häufiger gelesen als geschrieben. Daher sind Konventionen wichtig, die ein schnelles Lesen und Erfassen des Codes unterstützen.
- Die Einhaltung eines Abstraktionsniveaus fördert die Lesbarkeit. Damit Dokumentation gut zu lesen und zu verstehen ist, sollte in einer Beschreibung/Format nur ein Abstraktionsniveau verwendet werden. Andernfalls fällt es dem Leser schwer, Essentielles von Details zu unterscheiden. Wenn Detailauseinandersetzungen erforderlich sind, sollten diese nicht mit dem groben Überblick einer Funktion vermischt werden.
- Ich muss nicht alles dokumentieren was ich weiß. Was würde du einen neuen Teammitglied an den ersten beiden Tagen erzählen um ihn einen guten Start in das Projekt zu ermöglichen.
- Der Nutzen der Systemspezifikation steigt enorm, wenn nicht nur Entscheidungen / das gewählte Konzept beschrieben wird, sondern auch kurz die Alternativen betrachtet werden und die Gründe, die für die Entscheidung ausschlaggebend waren. In 2 Jahren weiß keiner mehr, warum das damals so entschieden wurde und die Reise geht evtl. neu los.
- Schreib ein Drehbuch. Erstell eine Schritt für Schritt Anleitung der Installation. Für Nutzenfälle. Für das Aufsetzen der eigenen Entwicklungsumgebung.
- Du schreibst lesbaren Code und hast einen hast einen konsistenten Code-Style. - warum dann ein unstrukturiertes Dokument? Nutze Kapitel, Unterkapitel. Fettdruck und Kursiv. Kurzfassungen und Absätze im Highlight fördern das Querlesen und das leichtere Finden von Informationen.
- Für Wenn ist das Dokument. Welchen Zweck hat das Dokument. Ein kurzes Wer bin ich reicht um zu verhindern das der Fachbereich das Klassenmodell in die Hand nimmt und..
- Der gezielte Einsatz von Diagrammen erhöht das Verständnis deutlich. Aber der Aufwand der Erstellung ist hoch und nur gerechtfertigt wenn auch ein Mehrwert entsteht. UML, GUI Skizzen Screenshots
- Tabellen können helfen - müssen aber nicht.
- Wir haben Definition of Ready und Definition of Done - lasst uns auch eine Definition of agile Documentation für uns erstellen.