Was genau beinhaltet 'Dokumentation'?

Wenn wir "Dokumentation" für ein Softwareprodukt sagen, was beinhaltet das und was sollte das nicht beinhalten?

Beispiel: Eine kürzlich gestellte Frage, ob Kommentare als Dokumentation betrachtet werden.

Es gibt aber auch viele andere Bereiche, für die dies eine berechtigte Frage ist, von denen einige offensichtlicher sind als andere:

• Handbücher (offensichtlich)
• Versionshinweise?
• Tutorials
• Bemerkungen
• Irgendwelche anderen?

Wo ist die Linie gezeichnet. Wenn es sich bei "Tutorial" beispielsweise um Dokumentation handelt, handelt es sich um "Video-Tutorial" -Dokumentation oder handelt es sich um etwas anderes?

Im Allgemeinen wird etwas in der Software erst dann „erledigt“, wenn es implementiert, getestet und dokumentiert ist. Daher diese Frage, welche Dinge sollten wir als Teil der Dokumentation betrachten, um etwas 'getan' zu betrachten.

_{Die Frage ergab sich aus den jüngsten Kundenfeedbacks auf unserer Konferenz und ergab, dass unser Dokument mehr „Muster“ benötigte, die wir zuvor nicht so gut in Betracht gezogen hatten, wie wir hätten haben sollen.}

_{Zielgruppe: Softwareentwickler, die unsere Datenbank (en), Programmiersprachen und zugehörigen Tools verwenden (z. B. Administrationsclients für diese Datenbank).}

Das Ziel der Dokumentation besteht darin, das Softwareprodukt zu beschreiben und zu erklären. Sie können die Dokumentation also als eine Reihe von Artefakten definieren, die zu dieser Beschreibung oder Erklärung beitragen. Sie würden wahrscheinlich keine verwandten Aktionen in Betracht ziehen als Teil der Dokumentation betrachten: z. B. ein einwöchiger Schulungskurs ist keine Dokumentation, aber die Kursmaterialien sind; Ein fünfminütiger Whiteboard-Chat ist keine Dokumentation, sondern ein Abbild des Whiteboards.

Unter Berücksichtigung des Ziels (Erklärung der Software) ist die Dokumentation fertig, wenn der Kunde mit der Erklärung zufrieden ist : So wie die Software fertig ist, wenn der Kunde mit der Software zufrieden ist. Bedenken Sie, dass der Kunde für die Dokumentation nicht immer mit dem Kunden identisch ist, der für die Software bezahlt: Support-Mitarbeiter, Tester, Verkäufer und andere benötigen ein gewisses Verständnis dafür, was die Software tut und wie sie funktioniert.

Dies hilft zu verstehen, wo Ihre Grenze für das, was in der Dokumentation enthalten sein soll, liegt. Verwenden von "reader" als praktische Kurzform, obwohl wir akzeptieren, dass Videos oder Audiodateien enthalten sein können: Alles, was dem Leser hilft, die benötigten Informationen über die Software zu erhalten, ist Dokumentation, die er verwenden kann, alles andere nicht. Wenn Ihr Kunde detaillierte Beschreibungen aller seiner Anwendungsfälle benötigt, muss dies Teil der Dokumentation sein. Ihre Entwickler benötigen wahrscheinlich Quellcode, Informationen zu Ihrem Versionskontroll-Repository und Build-Anweisungen: Dies ist eine Dokumentation für sie, die jedoch, wie oben beschrieben, nicht Bestandteil der Kundendokumentation ist.

Ich glaube, Sie haben bei einer Konferenz den falschen Teil aus Ihrem Gespräch genommen. Moderne Softwareentwicklungsmethoden empfehlen, dass das Entwicklungsteam eng mit seinen Kunden zusammenarbeitet (oder mit einem Product Owner, der als Kundenvertreter fungiert). Bei allen geleisteten Arbeiten wird die Definition von "erledigt" zwischen dem Team und seinem Kunden ausgehandelt und bei der Entwicklung der Software regelmäßig durchgeführt.

Das Problem, auf das Sie gestoßen sind, ist, dass Sie eine Diskrepanz zwischen dem hatten, was Sie für den Kunden benötigten, und dem, was er von Ihnen erwartete, sodass Sie am Ende die Überraschung "Hey, wo sind alle Muster?" Bekamen.

Was ist Dokumentation? Nun, es ist so ziemlich alles, was Sie aufgelistet haben, und vielleicht ein paar weitere Dinge, die Sie nicht getan haben. Aber niemand kann Ihnen sagen, wie viel Dokumentation Ihr Projekt benötigt. Jedes Projekt ist anders und es liegt an Ihrem Team, Ihrem Product Owner und Ihren Kunden, den Grad und die Art der Dokumentation zu bestimmen, die für Ihr Projekt erforderlich ist.

Einige Faktoren, die ins Spiel kommen würden:

• Entwickeln Sie Software v1.0 und wechseln Sie zu anderen Projekten, oder handelt es sich um ein laufendes, langfristiges Projekt? Kommentare / Designdokumente werden im letzteren Fall viel wichtiger. Auf der anderen Seite, wenn Ihr Kunde ein Tante-Emma-Laden ist und Sie eine Website für ihn schreiben, die Sie nie sehen werden ... Ich denke, die Codedokumentation ist nett, aber nicht so wichtig.
• Entwickeln Sie ein Handyspiel oder eine Software, die die Herzfrequenzmessung in einem Krankenhaus steuert? Ratet mal, welche Definition von "erledigt" viel mehr Dokumentation hat?
• Sind Ihre Kunden typische Endbenutzer oder andere Entwickler? Haben Sie ein API / SDK, das Sie verfügbar machen?
• Wie hoch ist das Fachwissen Ihrer Kunden? Dies wirkt sich auf die Auswahl von Video-Tutorials vs. schriftlichem Material vs. einer interaktiven Tutorial-App aus
• Kümmern sich Ihre Kunden darum, was sich von Version zu Version geändert hat? Einige tun. Die meisten nicht. Für wenige ist es das Gesetz (oder nahe daran), sich darum zu kümmern.

Dokumentation ist etwas, das gelesen werden soll, ohne es zu verändern.

Ich denke, Sie können mit zweckgebundener Definition nichts falsch machen ... aber nur, wenn Sie den Zweck richtig definieren.

• ^{Die genaue Definition des Dokumentationszwecks ist nicht ganz einfach. Unkompliziert (naiv, wenn Sie es wünschen) fällt natürlich auf, dass Dokumentation alles ist, was zum Lesen gedacht ist - während Code zum Vergleich alles ist, was zur Computerausführung gedacht ist . Hört sich an der Oberfläche gut an, nicht wahr? aber es stellt sich wirklich ziemlich hässlich heraus, wenn man tiefer gräbt.
   
  Ein guter Code berücksichtigt Lesbarkeitsprobleme und die Richtigkeit der Ausführung - dies macht die Unterscheidung zwischen "Lesbarkeit" bei der Definition der Dokumentation ziemlich nutzlos.
   
  Die sehr Proben Sie erwähnt haben, zeigen, was daran falsch ist. Kunden erwarten normalerweise, dass diese klar und deutlich geschrieben sindrichtig ausführen. Eine Beeinträchtigung der Lesbarkeit oder der Korrektheit kann zu einem Wasserfall der Kundenbeschwerden führen. Naive Unterscheidung hilft nicht, um herauszufinden, ob es sich bei den Beispielen um Code oder Dokumentation handelt.
   
  Wenn Sie sich vorstellen, mit Open Source zu arbeiten, wird die Verwendung der naiven Unterscheidung noch chaotischer . Sie laden es herunter, erstellen es und führen es aus - Sie lesen es nicht, es ist nur der richtige Code? Warten Sie, die Dinge sind irgendwie schief gelaufen und Sie haben den Code gefunden, um zu lesen, was dort vor sich geht. Hey, Sie haben gelesen, dass diese Dokumentation nicht ausgeführt wird. Und schließlich finden Sie einen Fehler in der Quelle und beheben ihn. Dies ist nun wirklich der Code. Es handelt sich nicht um eine normale Dokumentation, auch wenn Sie sie sorgfältig gelesen haben, um diesen Fehler zu beheben.}

Für die 'Beispiele', die Sie bereitstellen werden, könnte sich die Unterscheidung zwischen Lesen und Ändern als sehr wichtig herausstellen.

Wenn ein Beispiel in der dokumentierten Referenzumgebung bei unveränderter Ausführung fehlschlägt, handelt es sich um Ihren Fehler in der Dokumentation, den Sie akzeptieren und beheben müssen.

Wenn nun ein Problem mit einem geänderten Beispiel oder einer geänderten Umgebung vorliegt, ist dies nicht mehr Ihre Schuld - ich meine, es liegt kein Fehler in der Dokumentation vor, da die Dokumente nicht für Änderungen vorgesehen sind. Was auch immer Sie den Benutzern in einem solchen Fall helfen, es fällt unter die Support-Kategorie und ist kein Bugfix.

Alles, was die Frage "Wie gehe ich vor?" Beantwortet, ist Dokumentation.

Für Entwickler bedeutet dies Anforderungsspezifikationen ("Woher weiß ich, was zu schreiben ist"), Konstruktionsdokumente ("Wie gehe ich auf meine Anforderungen ein"), Rückverfolgbarkeitsmatrizen ("Woher weiß ich, dass mein Entwurf alle meine Anforderungen erfüllt"). Testpläne ( „wie kann ich wissen , meinen Code funktioniert“), Unit - Tests ( „wie kann ich wissen , ich Teile safisfied Anforderung X habe“), Inline - Kommentare ( "wie kann ich sicher , dass die nächste schlechte schlub versteht , warum ich es geschrieben hätte dieses Anweisungen zur Bereitstellung ("Wie verpacke ich dieses Produkt für die Installation") usw.

Für Benutzer bedeutet dies, dass Benutzerhandbücher ("wie verwende ich die Software"), Lernprogramme ("wie verwende ich diese spezielle Funktion"), Versionshinweise ("woher weiß ich, welche Fehler behoben wurden / welche neuen Fehlerfunktionen verwendet wurden hinzugefügt ") usw.