Link zu relevanter Dokumentation in Fehlermeldung einfügen?

Wir erstellen eine kommerzielle Bibliothek und Codebeispiele, die von externen Entwicklern verwendet werden. Wir haben eine (geschlossene, registrierten Benutzern zur Verfügung stehende) Dokumentation, in der ausführlich erläutert wird, wie die Bibliothek verwendet wird.

Viele der Entwickler sind Erstbenutzer, daher treten viele rudimentäre Fehler auf.

Ist es angebracht, Links zur Dokumentation in das Fehlerprotokoll aufzunehmen? Was sind die möglichen Nachteile? Ich kann einige vorhersehen, aber es scheint möglich, Folgendes zu überwinden

• Dokumentations-URL veraltet
• Versionsspezifische Fehler, die in der neuesten Dokumentation nicht berücksichtigt werden
• Etwas anderes stimmt nicht und wir verschwenden die Zeit des Entwicklers, indem wir ihn an ein irrelevantes Dokument senden

Ist es eine gute Idee, den fett gedruckten Text hinzuzufügen, wenn Sie unter einem Beispiel sehen, was ich meine?

[FEHLER] Fehler beim Ausführen des Ziels org.apache.maven.plugins: maven-archetype-plugin: 1.2.3: generate (default-cli) für das Projekt standalone-pom: Der gewünschte Archetyp existiert nicht (com.example.library). Archetypen: library-archetype-blank: 1.2.3.0) -> Weitere Informationen und mögliche Fehlerbehebung finden Sie unter http://example.com/docs/setting-up-an-archetype

Nach diesen Richtlinien für Fehlermeldungen und meiner Erfahrung sparen Menschen gerne Zeit, indem sie weder Dokumentation noch Hilfe lesen. Das Googeln eines Fehlers kann auch darüber hinausgehen. Fügen Sie daher einen Link hinzu, wenn sie einen Grund haben, darauf zu klicken.

Schließlich kennen Sie wahrscheinlich bereits Nielsens erstes Gesetz der Computerdokumentation: Die Leute lesen es nicht. Diese Erkenntnis ist noch stärker für Websites, auf denen Benutzer wirklich vor Lesungen zurückschrecken, die für ihre Aufgabe nicht wesentlich sind. Klicken Sie auf Hilfe? Noch nie.

Benutzer lesen die Systemdokumentation nur, wenn sie in Schwierigkeiten sind (das ist das zweite Gesetz). Sie sind besonders aufmerksam, wenn sie sich von einem Fehler erholen möchten. Vor diesem Hintergrund können Sie Fehlermeldungen als Bildungsressource verwenden, um Benutzern eine kleine Menge an Wissen zu vermitteln. Natürlich sollten Fehlermeldungen kurz und sachlich sein, ebenso wie alle Webinhalte. Fehlermeldungen können den Benutzern jedoch noch ein wenig über die Funktionsweise des Systems beibringen und ihnen Informationen geben, die sie für eine bessere Verwendung benötigen. Zu diesem Zweck ermöglicht die zugrunde liegende Technologie des Web eine weitere Richtlinie:

Hypertext-Links können verwendet werden, um eine kurze Fehlermeldung mit einer Seite mit zusätzlichem Hintergrundmaterial oder einer Erläuterung des Problems zu verbinden. (Übertreiben Sie das aber nicht.)

Ja, definitiv, ABER:

• Link Rot wird ein Problem sein. Generieren Sie den Link idealerweise dynamisch aus einem bekannten Zieldokument, erhalten Sie jedoch das Präfix aus einer beliebigen Form der Konfiguration. Sollte sich der Server ändern, können Sie älteren Code durch Aktualisieren dieses Konfigurationselements gültig halten. Sie können das Dokument auch lokal verfügbar machen, indem Sie diese Präfixkonfiguration ändern.
• Versionierung : In diesem Sinne, wenn Sie die Versionierung in gewisser Weise in den Link aufnehmen können, sodass der Link immer auf die richtige Version der Dokumentation verweist.
• Bearbeiten Sie das Dokument So etwas wie eine Wiki-Site für Ihre Dokumentation, auf der Sie Fehler dynamisch korrigieren können. Idealerweise können Benutzer auch direkt auf der Seite Kommentare abgeben. Dies erleichtert Ihren Benutzern die Teilnahme und das Finden der benötigten Informationen erheblich. Sie erhalten wertvolle Informationen, um Ihr Dokument in einem guten Zustand zu halten. Achten Sie jedoch darauf, dass Sie es regelmäßig überwachen und vor allem selbst aktiv teilnehmen .
• Generierte Vorlagen lassen Ihr Build-System die Basisvorlage für die Dokumentation direkt aus Anmerkungen im Code generieren. Halten Sie es einfach, aber dies stellt sicher, dass jeder Link immer auf eine gültige Dokumentation verweist. Wenn Sie ein Wiki verwenden, stellen Sie sicher, dass Sie diese Vorlagen einfach pushen können, und stellen Sie sicher, dass Sie die Dokumentationssite genauso bewerben können, wie Sie es für Ihren Code tun (haben Sie eine Entwickler-Site, die sich von der Prod-Site unterscheidet, und bewerben Sie Code für Prod Führen Sie die Einfügungen auf der Produktseite automatisch durch.

Wenn Sie mit Java oder .NET entwickeln, kann das Dokument in eine JAR-Datei oder eine DLL-Datei aufgenommen werden. Durch Ändern des Präfixes kann Ihr Code es stattdessen lokal abrufen.

Wenn Sie sich für den Wiki-Ansatz entscheiden, empfehle ich DokuWiki wärmstens, da es einfach ist und auf flachen Textdateien basiert, die es für die automatische Injektion aus dem Build-System sehr benutzerfreundlich machen würden. Trotzdem weiß ich nicht genug über Ihre Umgebung oder Kunden, um wirklich zu wissen, ob dies zu YMMV passt.

Einige der erfolgreichsten Tools, die ich erstellt habe, verfolgten einen ähnlichen Ansatz, bei dem die Fehlermeldung an den tatsächlichen Benutzer gerichtet war, der die Aufgabe höchstwahrscheinlich ausführen würde. Das bedeutete, dass ich eine Menge Ausnahmen abfangen und umbrechen musste, um sicherzustellen, dass der Fehler auf der entsprechenden Abstraktionsebene liegt. Ich habe auch sichergestellt, dass jede Fehlermeldung die wahrscheinlichsten Fehlerquellen enthält und auf mögliche Lösungen hinweist: "Haben Sie vergessen, den Konfigurationswert xxxx festzulegen?", "Stellen Sie sicher, dass xxx und yyy nicht in Konflikt stehen, indem Sie ihnen unterschiedliche Namen geben" usw. Wobei XXX und so weiter aus dem Kontext generiert werden, in dem der Fehler aufgetreten ist.

Dieser Ansatz war etwas einfacher, aber auch begrenzter. Es hatte jedoch den Vorteil, dass die Dokumentation immer vorhanden war, wenn sie benötigt wurde, ohne dass eine Verbindung möglich war.

Ihr Ansatz ist die nächste Entwicklung. Viel komplexer, hat aber auch viel mehr potenzielle Renditen. Es wird zwar teuer sein, aber wenn es richtig gemacht wird, zahlt es sich leicht aus.

Sie sollten lieber auf Offline-Dokumentation verweisen, die in der Bibliothek enthalten ist, als auf Online.

(com.example.library.archetypes: library-archetype-blank: 1.2.3.0) -> Weitere Informationen und mögliche Fehlerbehebung finden Sie unter /usr/share/myprog-3.8.1/docs/setting-up-an-archetype

(Wenn es sich um eine Windows-Bibliothek handelt, ist der Pfad natürlich anders.)

Die Vorteile hier sind:

• Auf diese Weise ist die Dokumentation immer mit der Bibliothek synchron. Die Leute entwickeln mit alten Bibliotheksversionen und beheben Fehler. Und Ihr Unternehmen kann seinen Namen ändern, den Namen des Produkts ändern oder jemand kann den Ball bei der Erneuerung fallen lassen example.com.

• Das Web ändert sich schnell. Der Link, den Sie geben, ist http, aber in einigen Jahren werden die wahrscheinlich wichtigsten Browser nur noch unterstützt https. Oder wir könnten alle zum gopherProtokoll zurückkehren.

• Die Fehlerbehebung bei Anwendungen erfolgt nicht immer in einer Umgebung mit Internetzugang (oder zumindest direktem Zugriff auf Ihre Domain).

• Sie erwähnen, dass sich Ihre Dokumentation hinter einer "Authentifizierungs" -Wand befindet. Es ist nicht angenehm, ein Konto auf einer Website erstellen zu müssen, um eine Fehlermeldung zu verstehen (aus diesem Grund müssen sich keine Personen anmelden).

Es gibt einen wirklich erfolgreichen Weg, um dieses Problem anzugehen. Stellen Sie sicher, dass die mit der Nachricht kombinierte Ausnahme so eindeutig ist, dass durch Einfügen in eine Websuche alle relevanten Beiträge zu genau diesem Problem leicht gefunden werden können.

Dies ist der geheime Grund, warum ich Nullzeiger-Ausnahmen so sehr hasse. Sicher, ich hasse es, dass wir sogar nach Null suchen müssen, aber was mich am meisten stört, ist, dass die einzige wirklich eindeutige Kennung, nach der ich suchen muss, eine flüchtige Zeilennummer ist, wenn ich auf eine stoße.

Ja, ich möchte nach diesen suchen können. Oh sicher, ich weiß, dass es passiert ist, weil etwas null gelassen und dann verwendet wurde. Was jedoch nicht immer sofort offensichtlich ist, ist, WARUM etwas null gelassen wurde.

Berücksichtigen Sie also alle diese anderen Dokumentationslösungen. Aber das Faulste, was Sie tun können, das mir am besten tut, ist, mir etwas zu geben, das ich googeln kann.

Bitte schön?