Dokumentation erniedrigend - wie geht man damit um?

Wichtig : Wir haben keinerlei Probleme mit der Quelltextdokumentation . Dies gehört zum regulären Code-Audit und wird auf dem neuesten Stand gehalten. Unser Problem liegt in der Entwicklerdokumentation (oder, wenn Sie möchten, "extern"), in kleinen blogähnlichen Tipps von Programmierern zu Programmierern, die in der Regel einmal geschrieben wurden und häufig zurückgelassen werden.

Wir verwenden ein Wiki-ähnliches System, um Programmiererdokumentationen zu erstellen - Artikel, die von Programmierern für Programmierer geschrieben wurden und die detaillierter beschreiben, wie ein bestimmtes Stück Code funktioniert. Diese Wiki-Seiten enthalten normalerweise:

• Motivationen für Designentscheidungen für Teile der API (zum Beispiel: Wir haben diese hässliche Sache getan, weil diese bestimmte Bibliothek von Drittanbietern möchte, dass die Dinge auf diese Weise erledigt werden, weil diese andere Bibliothek ..., weil ...)
• Erklärung, wie wir mit bestimmten allgemeinen Aufgaben umgehen (z. B. Anzeigen eines einfachen Popups, bei dem auf geeignete Anwendungsstile verwiesen werden muss, sich selbst in der Registrierungskomponente registriert und eine Schnittstelle implementiert werden muss, um von einer anderen Komponente automatisch "gescannt" zu werden)
• Good Practices (subjektiv, wir schreiben dieses Zeug tatsächlich auf)
• Umgebungskonfiguration, erforderliche Tools und deren Einrichtung

Im Allgemeinen geht es in erster Linie darum, Code zu schreiben, der aufgrund seiner Größe und seines Blogpost- / artikelähnlichen Charakters nicht zur normalen Codedokumentation passt.

Das Problem

Was die Einführung dieses Systems vor einigen Monaten angeht, habe ich heute das Gefühl, dass es mehr Probleme verursacht als löst. Beispielsweise:

• Menschen tun Schreibartikel ... aber sobald Code geändert, Wiki - Update selten folgt
• Viele Rubbelartikel , die jemand in Eile geschrieben und so hinterlassen hat
• Obwohl die Artikelanforderung normalerweise von der Projektleitung stammt, wird sie kaum auf ihre Richtigkeit / Zusammensetzung überprüft - was manchmal zu einer schlechten Qualität führt

Der übliche Abbau. Code geändert, Wiki bleibt gleich. Das nächste Mal, wenn jemand nach Informationen sucht, findet er normalerweise eine Menge veralteter, minderwertiger Dinge - und fragt sich, was los ist, ob die gefundenen Dinge genau sind oder (noch schlimmer) welche Teile davon. Und was helfen sollte, macht am Ende das Gegenteil.

Im Moment scheinen sich die Leute des Problems bewusst zu sein, einschließlich des Projektleiters, aber anscheinend scheint niemand die Mühe zu haben, etwas damit zu tun (oder hat interessantere Dinge zu tun).

Mein erster Gedanke war, alles in Vergessenheit zu geraten (nachdem ich einige Male hintereinander von veralteten "Tipps" gebissen wurde), aber ich denke, das könnte zu extrem sein. Einige Informationen sind erwähnenswert und manchmal gut zu lesen, aber das Problem ist immer noch dasselbe: Wie gehen Sie mit der "Aktualität" um ? Haben Sie es irgendwie mit dem Quellcode verknüpft (wenn die aktualisierte Version der Datei eingecheckt wird, wird der Autor des Artikels benachrichtigt, dass er möglicherweise Code / Artikel überarbeiten muss)? Haben bestimmte Personen die täglichen Grundlagen "überwacht"? Führen Sie regelmäßige Aufräumarbeiten durch?

Es hört sich so an, als würden Sie zu viele Kleinigkeiten im Wiki dokumentieren.

Dokumentieren Sie Codeblöcke und Methoden im Code . Versuchen Sie, Ihren Code selbstdokumentierend zu machen, damit Sie nicht viele Kommentare machen müssen. Das Schreiben von Unit-Tests kann ebenfalls hilfreich sein.

Dokumentdesignentscheidungen und -architekturen werden im Wiki genauer beschrieben, sodass das Wiki nicht häufig geändert werden muss oder viel Arbeit erfordert, um Änderungen vorzunehmen. Wenn viele Leute in Ihrem Team die Architektur bereits kennen und das Team nicht schnell wächst, gibt es möglicherweise keine überzeugenden Gründe, um sie überhaupt zu dokumentieren. Angesicht zu Angesicht ist häufig der beste Wissenstransfer.

Veraltete Informationen werden sofort umgeschrieben oder gelöscht. Je länger sie gespeichert bleiben, desto schwieriger wird es, sie zu erkennen und desto mehr davon werden angesammelt. Wenn Sie keine Zeit haben, löschen Sie es einfach und markieren Sie den Artikel als überarbeitungsbedürftig. Dies verlangsamt Sie und wird trotzdem in der Versionskontrolle gespeichert.

Dokumentieren Sie Vorgänge, indem Sie sie in einem Skript oder einer Installationsdatei automatisieren . Andernfalls lassen Sie sie im Wiki, aber jedes Mal, wenn jemand eine Prozedur aus dem Wiki verwendet, bitten Sie ihn, den Artikel zu verbessern oder Teile des Prozesses zu automatisieren.

Blogartikel gehören in Blogs . Wenn Menschen ihre persönlichen Meinungen und Ratschläge mitteilen möchten, erstellen Sie dafür einen Unternehmensblog. Sie möchten wahrscheinlich nicht, dass ihre Artikel geändert werden, und niemand wird sie ohnehin ändern. Lassen Sie sie also nicht das Wiki überladen.

Die Dokumentation sollte als lieferbar behandelt werden und daher den Regeln der Rückverfolgbarkeit und Abnahme sowie der angemessenen zu entwickelnden Zeit unterliegen.

Es ist nicht ungewöhnlich, dass Leute Software-Dokumentation als gegeben "erwarten", wenn dies nicht der Fall ist.

Radikal aber effektiv. Wenn jemand ein neues Modul geschrieben hat, es aber nicht dokumentiert hat - öffnen Sie die Aufgabe im Issue Tracker erneut und verhindern Sie, dass nicht dokumentierter Quellcode versandt wird, falls dies erforderlich ist. Wenn Sie den Entwicklern erlauben, die Quelltextdokumentation als notwendiges Übel zu behandeln, erhalten Sie fragmentarische und veraltete Dokumentationsfetzen.

In meinem letzten Projekt verfolgen wir zumindest alle erforderlichen Bibliotheken von Drittanbietern. Wenn jemand eine neue Bibliothek einführt, diese jedoch nicht dokumentiert ist, setzen wir die Lösung zurück, bis die Dokumentation eingeführt ist. Ohne solch einen radikalen Ansatz würde es Chaos geben. Ein unerfahrener Entwickler könnte beispielsweise eine Bibliothek verwenden, deren Lizenz im Widerspruch zur Lizenz unserer Software steht.

Wenn sich etwas schnell ändert, sollte es nicht außerhalb des Codes gepflegt werden.

Motivationen für Designentscheidungen für Teile der API

Dies ist besonders wichtig, um den Code möglichst genau einzuhalten. Wie in derselben Quelldatei. Auf diese Weise wird es etwas schwieriger, die Datei zu ignorieren, wenn jemand sie berührt, und weniger Eingaben von Personen an TheDailyWTF zu veranlassen, die nicht wissen, dass die externe Dokumentation vorhanden ist.

Der übliche Abbau. Code geändert, Wiki bleibt gleich.

Hier wird "ausführbare Dokumentation" - Unit-Tests - sehr nützlich. Wenn sich der Code ändert und sich die Tests nicht ändern, bricht der Build ab. Das Schreiben von Tests als Dokumentation erfordert natürlich etwas Geschick. Aber auch das Schreiben (guter) externer Dokumentation.

Eine gute Möglichkeit, mit dem Problem umzugehen, besteht darin, es in den Prozess einzubeziehen. Wenn Sie einen Code-Trace für die relevanten Seiten im Wiki haben, kann ein Entwickler leicht herausfinden, was möglicherweise aktualisiert werden muss. Stellen Sie außerdem sicher, dass die Prüfer in einer Codeüberprüfung sicherstellen, dass das Wiki auf dem neuesten Stand ist (in Bezug auf das Update).

Eine andere Möglichkeit, es als Teil des Prozesses hinzuzufügen - da Sie ein agiles Modell verwenden, das Teil des Planungsprozesses für Iterationen ist, besteht darin, geplante Änderungen im Wiki zu aktualisieren. Das Wiki dient dann als Ressource "So sollte es funktionieren".

Wenn Sie eine .NET-Sprache verwenden, schauen Sie sich ( Sandcastle ) an, das die XML-Dokumentation (/// in C #) aufnimmt und in das MSDN-Hilfeformat konvertiert.

Das Format enthält Beschreibungen, Kommentare und bietet die Möglichkeit, Codebeispiele sowie einige andere Funktionen einzuschließen. Sie können in den Formaten .CHM, .HsX, .MSCH und HTML / ASP.NET ausgeben. Das eigentliche Projekt wird Ihrer Projektmappe hinzugefügt und auf dem Buildserver erstellt. Wir haben dies getan und stellen jede Version auf einer Website bereit, und die Verbraucher sind begeistert, da die Dokumentation für die Version relevant ist und ständig aktualisiert wird.

Sie können auch angeben, was in die Dokumentation aufgenommen werden soll. Derzeit gibt es zwei Projekte: eines für externe Verbraucher, die nur die Verträge und die entsprechenden Elemente (Klassen, Aufzählungen usw.) enthalten, und eines für interne Entwickler, die alles in der API enthalten, einschließlich privater und interner gekennzeichneter Elemente.

Dies ist die einzige Dokumentation, die wir verwenden, da Motivationen und Macken bei der Verwendung der API im Abschnitt "Kommentare" der Dokumentation enthalten sein können. Der Prozess funktioniert gut, wo ich arbeite.

Ich würde mich auf zwei Bereiche konzentrieren: 1) Den Code. 2) Notizen und Dokument ohne Code.

1) Der Code.

Versuchen Sie, es selbst zu dokumentieren. In der Vergangenheit habe ich festgestellt, dass das oft empfohlen, aber selten gut erklärt wurde, also ...

Anstelle dieser Art von Pseudocode:

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

Machen Sie Code, der ungefähr so ​​aussieht:

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

Verwenden Sie die Quellcodeverwaltung, um die Informationen zu verfolgen, wer was wann getan hat.

2) Der Nicht-Code

Verwenden Sie ein Wiki und ein Abschriftenformat, um diese Informationen zu pflegen. Machen Sie es Teil des Jobs. Publiziere es, poste es und blogge es. Richten Sie eine wöchentliche oder monatliche Standardbesprechung ein, um alte und neue Inhalte zu überprüfen. Mache es zu einem Mantra, dass, wenn jemand nach etwas fragt, die Antwort gegeben wird ... zusammen mit dem Gedanken "Sollte dies das nächste Mal im Wiki sein, wenn jemand fragt?"