Moderne Software-Dokumentation
Softwareentwicklung besteht aus dem Schreiben von Tests, Code und Dokumentation. Obwohl die testgetriebene Entwicklung (TDD) sehr populär geworden ist, haben viele Entwicklungsteams immer noch Schwierigkeiten, die richtige Dokumentation zu erstellen. Das Schreiben von zu viel Dokumentation ist verschwenderisch, aber eine gewisse Dokumentation ist notwendig, damit alle Beteiligten auf dem gleichen Stand sind.
Eine wirksame Dokumentation stellt sicher, dass Stakeholder, Entwickler und Benutzer auf derselben Seite stehen. Entwickler können Dokumentation für andere Entwickler schreiben, um den Code besser zu verstehen; Produktmanager können Dokumentation für Entwickler schreiben, um die Anforderungen besser zu verstehen; oder die Organisation kann Dokumentation für Endbenutzer schreiben.
Der Umfang der erforderlichen Dokumentation hängt vom jeweiligen Projekt ab. Bei kleinen Softwareprojekten ist möglicherweise keine Systemdokumentation und bei internen Projekten keine Support-Dokumentation erforderlich. Es liegt an Ihrem Team zu entscheiden, wie viel erforderlich ist, und dies gegen die Kosten abzuwägen, die erforderlich sind, um die Dokumentation aktuell zu halten.
Wie beschreiben Sie eine gute Dokumentation?
Die wichtigste Regel einer guten Dokumentation ist, dass sie so einladend wie möglich sein sollte. Das bedeutet, dass wir uns bemühen sollten, sie so klar wie möglich zu formulieren, ohne irgendwelche Schritte zu übergehen. Wir sollten es vermeiden, Annahmen darüber zu treffen, was unsere Benutzer wissen könnten.
Wie kann man Dokumentation in einem Satz verwenden?
(1) Die Antragsteller müssen Belege vorlegen. (2) Wir haben nicht genügend Unterlagen, um Ihren Antrag zu bearbeiten. (3) Es dauerte ewig, die für die Einreise erforderlichen Unterlagen zu beschaffen – was für ein Geschäft! (4) Die Drogen sind spurlos verschwunden, ohne jegliche Unterlagen.
Was sind die Beispiele für die Dokumentation?
Beispiele sind Benutzerhandbücher, Weißbücher, Online-Hilfen und Kurzanleitungen. Dokumentation auf Papier oder in Papierform ist immer seltener geworden. Die Dokumentation wird häufig über Websites, Softwareprodukte und andere Online-Anwendungen verbreitet.
Bewährte Praktiken der Code-Dokumentation
Im ersten Szenario lernen Sie Harlow kennen. Heute ist Harlows erster Tag in einem neuen Projekt. Das Team verfügt über eine gut etablierte Codebasis, eine großartige Arbeitsumgebung und eine robuste Test-Suite. Als Harlow sich an ihren Schreibtisch setzt, freut sie sich darauf, sich mit dem Team vertraut zu machen. Nach dem morgendlichen Stand-up-Meeting wird sie von ihrem Kollegen Riley mit einer leichten Grimasse auf die Projektdokumentation zur Installation hingewiesen. Er erwähnt, dass die Unterlagen “vielleicht ein wenig veraltet sind, aber hoffentlich ausreichen, um loszulegen.” Harlow verbringt dann den Rest des Tages damit, der Dokumentation zu folgen, bis sie nicht mehr weiterkommt und gezwungen ist, sich durch den Code zu wühlen oder Kollegen um Rat zu fragen. Was vielleicht ein paar Minuten gedauert hätte, wird zu einer tagelangen Frustrationsübung, die Harlows anfängliche Begeisterung zunichte macht.
Im zweiten Szenario lernen Sie Harrison kennen. Er arbeitet an einer Webanwendung und findet eine Bibliothek, die auf den ersten Blick unglaublich nützlich für sein Projekt erscheint. Als er versucht, sie in seine Codebasis zu integrieren, stellt er fest, dass Teile der API in der Dokumentation beschönigt werden oder sogar undokumentiert zu sein scheinen. Schließlich gibt er das Projekt zugunsten einer anderen Lösung auf.
Beispiel für eine Software-Dokumentation
Das Schreiben von Dokumentation ist oft wichtiger als das Schreiben von Code selbst. Und warum? Nun, wenn niemand weiß, wie Ihr Code zu verwenden ist, wird ihn auch niemand verwenden. Sie müssen in der Lage sein zu erklären, wie Ihr Code funktioniert und warum er so funktioniert, wie er funktioniert. Auf diese Weise werden andere Entwickler wissen, wie sie ihren Code in demselben Stil wie Sie schreiben können. Wenn Sie Beispiele für die Art und Weise, wie Sie Ihren Code implementieren, bereitstellen, werden andere den Kontext verstehen, in dem sie Ihre Software verwenden können.
Anhand dieser drei Punkte können Sie bestimmen, WAS Sie dokumentieren sollten. Sie denken vielleicht, dass Sie alles dokumentieren sollten, aber das ist nicht unbedingt richtig. Sie sollten das dokumentieren, was Sie für den wichtigsten Teil Ihrer Software halten und was andere am häufigsten verwenden werden. Wenn diese Konzepte kristallklar sind, können Sie die versteckteren Teile Ihres Codes dokumentieren, falls dies erforderlich ist.
Diese Regeln mögen sehr offensichtlich erscheinen, aber Sie wären überrascht, wie oft diese Regeln beim Schreiben von Dokumentation nicht beachtet werden. Wenn Sie Konzepte erklären, sollten Sie einen sehr freundlichen Ton verwenden. Sie wollen, dass die Leute etwas über Ihre Software lesen, und Sie sollten ihnen nicht das Gefühl geben, dass sie weniger gut als Entwickler sind, weil sie Ihren Code nicht sofort verstehen. Sie sollten auch ins Detail gehen und weitreichende Beispiele für die Implementierung der Software geben, aber nicht zehnmal das Gleiche schreiben.
Leitlinien für die Software-Dokumentation
Im ersten Szenario lernen Sie Harlow kennen. Heute ist Harlows erster Tag in einem neuen Projekt. Das Team verfügt über eine gut etablierte Codebasis, eine großartige Arbeitsumgebung und eine robuste Test-Suite. Als Harlow sich an ihren Schreibtisch setzt, freut sie sich darauf, sich mit dem Team vertraut zu machen. Nach dem morgendlichen Stand-up-Meeting wird sie von ihrem Kollegen Riley mit einer leichten Grimasse auf die Projektdokumentation zur Installation hingewiesen. Er erwähnt, dass die Unterlagen “vielleicht ein wenig veraltet sind, aber hoffentlich ausreichen, um loszulegen.” Harlow verbringt dann den Rest des Tages damit, der Dokumentation zu folgen, bis sie nicht mehr weiterkommt und gezwungen ist, sich durch den Code zu wühlen oder Kollegen um Rat zu fragen. Was vielleicht ein paar Minuten gedauert hätte, wird zu einer tagelangen Frustrationsübung, die Harlows anfängliche Begeisterung zunichte macht.
Im zweiten Szenario lernen Sie Harrison kennen. Er arbeitet an einer Webanwendung und findet eine Bibliothek, die auf den ersten Blick unglaublich nützlich für sein Projekt erscheint. Als er versucht, sie in seine Codebasis zu integrieren, stellt er fest, dass Teile der API in der Dokumentation beschönigt werden oder sogar undokumentiert zu sein scheinen. Schließlich gibt er das Projekt zugunsten einer anderen Lösung auf.