Nachdem ich auf Fehler in der technischen Dokumentation gestoßen bin, die mit ziemlicher Sicherheit auf eine unvollständige Bearbeitung nach dem Kopieren aus früheren Dokumentationen zurückzuführen sind, bin ich neugierig, mit welchen Techniken dieses Problem vermieden werden kann.
Leider scheint es schwierig, das Programmierprinzip von Don't Repeat Yourself strikt anzuwenden, da ein Großteil der Dokumentation in einer menschlichen Sprache geschrieben ist, die für das automatische Einfügen von Makros weniger geeignet ist.
(Automatische Konsistenz könnte für Tabellen und Diagramme mit einer regelmäßigen Struktur möglich sein, und oft könnten solche Merkmale automatisch aus Daten auf niedrigerer Ebene generiert werden. Dies würde nicht unbedingt die Konsistenz mit dem tatsächlichen Produkt garantieren, aber [abgesehen von Fehlern in der Übersetzungssoftware] Beschreibungen würden es tun von der unteren Ebene aufwärts konsistent sein. Wenn sich dies bis zur Hardwarebeschreibungssprache erstrecken würde, wären nur Übersetzungsfehler ein Problem, aber ich weiß nicht, ob das praktikabel ist und dies weniger für die Architekturdokumentation als für die Implementierungsdokumentation gelten würde.)
Die Verwendung von Makros so weit wie möglich wäre hilfreich (z. B. könnten viele numerische Ersetzungen automatisiert werden), und es könnte möglich sein, Abhängigkeitsinformationen einzuschließen, um hervorzuheben, wenn Änderungen in bestimmten Teilen des Dokuments (oder Informationssystems) Änderungen in anderen Teilen erfordern könnten des Dokuments. In einigen Fällen kann die automatische Generierung einer Dokumentation, die nur geringfügige Änderungen für die Lesbarkeit erfordert, praktisch sein und die Verwendung von Copy-Paste minimieren.
Welche praktischen Techniken helfen, unvollständige Änderungen an der Dokumentation zu vermeiden?
Dies ist ein schwieriges Problem. Wenn Ihr Unternehmen nicht über die Ressourcen verfügt, um die gesamte Dokumentation zu jeder Version vollständig zu überprüfen – und wenn ja, frage ich mich, wie sie wettbewerbsfähig bleiben –, dann sind Sie hier in Gefahr. Meiner Erfahrung nach können Sie einige Dinge tun, um das Problem zu beheben, wenn es auftritt, und einige Dinge, um die Wahrscheinlichkeit des Auftretens zu verringern .
Hier sind Techniken, die ich verwendet habe, um fehlende Updates zu finden und zu beheben:
Schneller visueller Scan der relevantesten Dokumentation. Dies ist keine vollständige Überprüfung (Sie haben wahrscheinlich keine Zeit), aber ich versuche, zumindest meine Augäpfel über jede Seite in verwandten Dokumenten / Abschnitten zu führen, um die Möglichkeit zu berücksichtigen, dass mir etwas ins Auge springt. Das passiert tatsächlich.
Wenn ein Feature (API-Funktion, GUI-Element, Schema-Element usw.) geändert oder entfernt wurde, durchsuche ich die Dokumentation nach relevanten Schlüsselwörtern wie dem Namen der Funktion/des Elements (wie auch immer wir in der Dokumentation darüber sprechen). Dies hilft, Streuverweise zu finden, wie z. B. die Dokumentation einer anderen Funktion, die sie mit der geänderten vergleicht. Dies hat mir geholfen, Fälle wie "Die X-Funktion macht blah blah blah; sie ist der Y-Funktion ähnlich, außer ..." zu erkennen, wo sich Y geändert hat.
Wenn sich das Verhalten geändert hat, dann haben sich wahrscheinlich auch die Testfälle geändert. Ich versuche, mit den Testern zu chatten, die die neu geänderte Funktion testen werden, um herauszufinden, welche anderen Testfälle sie ändern mussten. (Hinweis: Obwohl ich Zugriff auf ihr Testfall-Repository habe, finde ich es einfacher, stattdessen ein wenig Zeit mit einem Tester zu sprechen. Die Tester kennen ihre Testfälle viel besser als ich es je tun werde. Aus ähnlichen Gründen fragen sie im Allgemeinen mir, welche signifikanten Änderungen ich in der Dokumentation vorgenommen habe.)
Bei einem Projekt mit mehreren Autoren wähle ich Peer-Reviewer aus, die an Teilen der Dokumentation gearbeitet haben, für die ich nicht so viel Zeit aufgewendet habe. Sie werden bemerken "Oh, wenn sich das geändert hat, dann muss sich diese andere Sache in "meinem" Dokument auch ändern", bevor ich es tue.
Hier sind einige Techniken, die ich verwendet habe, um dieses Problem zu verhindern oder zumindest die Wahrscheinlichkeit zu verringern. Betrachten Sie dies als defensives Schreiben :
Im Geiste von „don’t repeat yourself“ (DRY) versuche ich, wenn ich dieselben Informationen an mehr als einer Stelle einfügen muss, sie in einem Blob zu abstrahieren, den ich an allen erforderlichen Stellen durch Referenz einfügen kann gehen. Das Schreiben einer fragmentierten Dokumentation wie dieser ist schwieriger (Sie müssen darauf achten, dass Ihr Blob in allen Kontexten gültig bleibt), aber diese Wiederholungsebene kommt meiner Erfahrung nach nicht so oft vor. Aber es kommt manchmal vor, also verwenden Sie Include-Tools, wenn dies der Fall ist.
Manchmal wissen Sie, wenn Sie etwas schreiben, dass es mit einem anderen Teil der Dokumentation verbunden ist. Verwenden Sie Kommentare (oder einen beliebigen Anmerkungsmechanismus, den Ihr Tool unterstützt), um sich selbst auffindbare Erinnerungen hinzuzufügen. Kommentare sind nicht nur für Code; Sie können auch in Doc Source nützlich sein. (Meine Quelle ist XML; Ihre Laufleistung kann variieren.)
Ich habe das noch nicht in "Produktion" gemacht (nur als Test), aber kommentiere deine Screenshots .
Seien Sie neugierig, wenn es um Ihre Fehlerdatenbank geht. Ich werde automatisch auf alle Fehler in bestimmten Komponenten kopiert, und ich überprüfe häufig neue Fehler und füge mich selbst der CC-Liste hinzu, wenn es so aussieht, als ob sie mich betreffen könnten. Ja, dies generiert eine Menge E-Mails, aber es lohnt sich, Notizen von Testern und auch von Entwicklern zu sammeln, die festgestellt haben, dass sie etwas anderes ändern mussten, um dies zu implementieren. Ich bekomme viele meiner besten Informationen aus Bugzilla-Benachrichtigungen.
Gehen Sie bei der anfänglichen Projektschätzung gründlicher vor. Zu Beginn des Release-Planungszyklus, wenn der Produktmanager, das Entwicklungsteam und andere die zu erledigende Arbeit festlegen, haben Sie wahrscheinlich – wenn Sie wie die meisten Menschen sind – eine Zeile zum Projektplan hinzugefügt sagte so etwas wie "Dokument aktualisieren (N Wochen)". Aber wenn Sie im Vorfeld etwas mehr tun, können Sie einige Probleme für sich und die Tester vermeiden. 1Während die Entwickler analysieren, was sich ändern wird, wenn sie das und das tun, können Sie dasselbe für das Dokument tun. Anstelle dieser Zeile "Dokument aktualisieren" könnten Sie also Elemente wie "Dokumentieren Sie neue Funktion X", "Aktualisieren Sie Funktion Y (das sich aufgrund von X geändert hat)", "Aktualisieren Sie die Dokumentation des Beispiels, das Y und Z verwendet" und "Überprüfen Sie die Dokumentation von Y für Aufprall". Während Sie mit Ihrem freundlichen Tester darüber sprechen, erfahren Sie möglicherweise, dass Ihr Tester weiß, dass sich auch ein Teil von Z ändern muss, sodass Sie früher darüber nachdenken können. Mit anderen Worten, je mehr Ihr Team frühzeitig über die Auswirkungen spricht, desto einfacher wird es für Sie, Ihre Dokumentänderungen systematisch und mit weniger panischer Hektik am Ende vorzunehmen.
1 Sie kommen jetzt vielleicht auf die Idee, dass ich denke, dass die Tester Ihre natürlichen Verbündeten sind. Sie sind. Sie und sie stehen oft am Ende der Informationspipeline, nicht weil Sie jemand ausschließen wollte, sondern weil Menschen, die sich auf eine eng begrenzte Aufgabe konzentrieren, die Auswirkungen nicht immer selbst erkennen. Zusammenarbeiten.
Der Code ist bereits eine Form der Dokumentation dessen, was das System tut. Das ist eher der Sinn von Hochsprachencode, das Verständnis von Systemen für menschliche Leser zu erleichtern.
Dies ist ein Hinweis auf eine Lösung. Fragen Sie sich: "Für wen ist die Dokumentation?" Sollen Programmierer mit anderen Programmierern in Ihrer Organisation kommunizieren? Tun Sie dann, was Sie können, um den Code klar, prägnant, nicht überraschend und TROCKEN zu gestalten. Bei DRY geht es mehr um die Zukunft als um die Gegenwart.
Und es hat keinen Sinn, kaputte Dokumentation aufzubewahren. Sie wären besser dran, die Dokumente zu verwerfen und jede Möglichkeit auszuschließen, dass jemand einen technischen Fehler macht, indem Sie auf möglicherweise fehlerhafte Dokumentation vertrauen. Schlechte Dokumentation ist erst dann schlecht, wenn sie einem um die Ohren fliegt. Bis dahin vermittelt es ein falsches Gefühl der Sicherheit.
Ist es für einen Programmmanager? Versuchen Sie dann, eine Dokumentation zu schreiben, die klar und prägnant ist und sich nicht hinter technischen Schlagworten und faux juristischer Sprache versteckt. Die meisten Leute halten mit der Dokumentation nicht Schritt, weil sie es schwierig finden, das bereits Geschriebene zu verstehen, den Stil nur schwer nachzuahmen und es verabscheuen, Make-Work zu machen. Es macht wenig Sinn, kleinste technische Details in die Dokumentation aufzunehmen. Andernfalls hätten wir eine Programmiersprache entworfen, die MS-Word-Dokumente als Quelldateien verwendet.
Ist es für Benutzer? Dann ist Ihre Dokumentation Teil Ihres Produktes. Sie müssen den Aufgaben bestimmte Zeit und wahrscheinlich bestimmte Personen widmen, die mit dem Schreiben von Dokumentationen Karriere machen. Die Projektiteration ist ohne die Benutzerdokumentation – eine Form der Benutzeroberfläche – nicht vollständiger als die Funktionen, die sie abdecken würde. Ich neige dazu, solche erklärenden Texte lieber neben dem Feature auf dem Bildschirm zu platzieren.
Und das ist generell ein Problem bei allen Teilen eines Systems: Wie nah liegen eng gekoppelte Komponenten? Sie werden es in Ihren Datenbankschemadefinitionen sehen, wenn Sie sie über rohe SQL-Skripte verwalten. Es tritt bei Berichten auf, die in Ihrem System generiert werden, wenn der Berichtscode „weit entfernt“ von der Berichtsbenutzeroberfläche ist. Verwandte Teile des Systems zusammenzuhalten, ist die einzige Möglichkeit, ein Auseinanderdriften zu vermeiden, wie etwa zwei Proben einer Art, die im Laufe der Zeit voneinander abweichen, nachdem sie durch einen Ozean getrennt wurden.
Beachten Sie auch, dass Sie nicht dem „offensichtlichen“ Prozess zum Schreiben von Dokumentation folgen müssen, den Programmmanager immer zu lieben scheinen. Als ich das letzte Mal in einer stark dokumentierten Umgebung gearbeitet habe, habe ich mindestens 50 % meiner Zeit mit Dokumentation verbracht. Aber obwohl mein Programmmanager wollte, dass die Dokumentation vor dem Code geschrieben wird, habe ich nichts dergleichen getan. Ich habe sie parallel geschrieben. Ich musste den Code schreiben, um herauszufinden, was in der Dokumentation stehen würde. Ich wurde dafür gelobt, dass ich die beste Dokumentation und Fristenrate im Unternehmen habe.
Aber die Moral der Geschichte ist nicht „mach es auf meine Art“. Es ist so, dass jedes Unternehmen seine eigene Kultur hat, die bestimmte Dinge über andere stellt. Nutzen Sie dieses Wissen zu Ihrem Vorteil. Kodierungszeit von Dokumentationszeit stehlen oder umgekehrt. Schreiben Sie beliebigen Code, um sich wiederholende Aufgaben zu automatisieren. Hinterfragen Sie grundsätzliche Behauptungen und versuchen Sie, den Arbeitsaufwand zu minimieren.
Monika Cellio
Paul A. Clayton