Wie können wir die Überprüfung der HTML-Dokumentation vereinfachen?

Zusammenfassung: Ich suche nach einer Möglichkeit für Reviewer, bei einem großen HTML-Projekt so nah wie möglich „inline“ kollaborativ zu kommentieren.

Das Problem im Detail

Ich arbeite in einem Team, das ein großes Produkt dokumentiert. Der HTML-Dokumentationssatz hat Hunderte von einzelnen Seiten (mit hierarchischem Inhaltsverzeichnis in der Seitenleiste, wie Sie es erwarten würden); Ein PDF des gesamten Dokumentensatzes umfasst mehr als 5000 Seiten.

Wenn wir ein neues Feature dokumentieren oder umfassende Verbesserungen wie Reorganisationen vornehmen, veröffentlichen wir einen HTML-Build zur Überprüfung durch Entwickler, QA, Support, den Produktmanager und andere Autoren. Wir veröffentlichen den gesamten Dokumentensatz in diesem Build, nicht nur die geänderten Seiten, da der Kontext manchmal wichtig ist. Um dies abzumildern, stellen wir Links zu den spezifischen Themen bereit, die sich geändert haben. Wir fügen diese Links tatsächlich dem Dokumentplan hinzu, einer Spezifikation, die wir früher erstellt haben und die die beabsichtigten Änderungen beschreibt – auf diese Weise können die Leute, wenn sie wollen, den Hintergrund sehen, warum wir eine bestimmte Änderung vorgenommen haben. Der Dokumentplan ist eine Seite im internen Wiki.

Wenn wir jetzt eine Überprüfungsanfrage versenden, verweisen wir die Leute auf diese Wiki-Seite und bitten die Leute, ihr Feedback als Kommentar zu posten. Dadurch kann jeder das Feedback des anderen sehen, was (a) weniger Wiederholungen im Vergleich zu individuellen Antworten und (b) eine frühere Entdeckung von Meinungsverschiedenheiten zwischen den Bewertern bedeutet. Aber lange Kommentarketten können auch mit Threading schwer zu navigieren sein. Und die Leute müssen noch etwas zusätzliche Arbeit leisten, um diese Kommentare zu schreiben, weil sie uns sagen müssen, worauf sie reagieren. Typische Kommentare beginnen mit so etwas wie „In ‚Installieren von Plugins‘ ist die Beschreibung im dritten Absatz nicht ganz richtig, weil …“.

Dieser Ansatz funktioniert für uns besser als E-Mail-Antworten oder individuelle Kommentare zu PDFs nur zu ausgewählten Themen. (Wir haben beides gemacht.) Gibt es eine Möglichkeit, es noch einfacher zu machen, indem man es den Leuten erlaubt, Kommentare direkt im HTML-Code anzuhängen, ähnlich wie das Kommentieren von Google Docs, aber ohne unseren großen Dokumentensatz in einige importieren zu müssen anderes Tool nur für diesen Zweck? Oder ist der aktuelle Ansatz das Beste, was wir ohne viel zusätzliche Arbeit tun können?

Wir möchten es den Leuten leicht machen, Kommentare zu kommentieren und die Kommentare anderer zu sehen. Die Messlatte, die es zu schlagen gilt, sind Kommentare auf einer Wiki-Seite. Wir sind nicht daran interessiert, einen großen HTML-Dokumentsatz in ein anderes Tool zu importieren (das die Leute lernen müssten). Ich frage mich, ob es beispielsweise bereits ein Javascript-Paket gibt, das wir in diese Builds einfügen können, um dieses Ziel zu unterstützen, oder ob es eine andere Möglichkeit gibt, dieses Ziel zu erreichen.

Werkzeuge im Einsatz

Wir verwenden die Quellcodeverwaltung (Git), wobei die Feature-Arbeit an Branches durchgeführt wird. Die Review-Builds werden von diesen Branches erstellt und sind persistent. (Die meisten unserer Prüfer fühlen sich nicht wohl dabei, den HTML-Quelltext zu überprüfen, oder ich würde all dies umgehen, indem ich sie den Rohquelltext auf dem Zweig überprüfen lasse.)

Wir verwenden Madcap Flare, um die Dokumente zu erstellen und zu erstellen. Flares Schema für die Dokumentenquelle ist ein erweitertes HTML; Der gesamte HTML-Code ist gültig, außerdem fügen sie einige Tool-spezifische Tags hinzu, die zur Erstellungszeit verwendet werden. Die Ausgabe ist herkömmliches HTML.

Wir verwenden Jenkins, um den Build-Prozess zu verwalten. Jenkins ruft derzeit ein Skript auf, das den Haushalt erledigt und madbuild.exe (die Build-Engine von Flare) aufruft. Dieses Skript veröffentlicht den HTML-Code auf einem internen Server. Im Prinzip könnten wir daher das Build-Skript modifizieren, um etwas Zusätzliches in die Ausgabe nur für diese Branch-Builds einzufügen. Wir besitzen den Server, also können wir ihm bei Bedarf Dinge hinzufügen (z. B. eine Möglichkeit, Kommentare zu speichern).