Was genau beinhaltet 'Dokumentation'?

12

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).}

documentation terminology

— Dan McGrath
quelle

2

Kommentare zu Downotes sind immer willkommen. Leider liefern Zahlen nicht viel konstruktive Kritik, um zu verstehen, wo man sich verirrt hat :)

— Dan McGrath

1

Softwaredokumentation oder Quellcodedokumentation ist geschriebener Text, der der Computersoftware beiliegt. Entweder wird erklärt, wie es funktioniert oder wie es verwendet wird, und es kann für Personen mit unterschiedlichen Rollen unterschiedliche Bedeutungen haben. - Der Schlüsselsatz lautet: "Kann für Personen mit unterschiedlichen Rollen unterschiedliche Bedeutungen haben". Was ist Ihr Publikum? (Noch nicht abgestimmt, aber ich vermute, die Unbestimmtheit und Offenheit der Frage ist schuld).

— Yannis

Siehe auch: Sind Kommentare eine Form der Dokumentation

— Dynamisch

2

Diese Frage schreit nach jemandem, der ein Venn-Diagramm zeichnet.

— MathAttack

6

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 würde Kursmaterialien nur dann als Dokumentation betrachten, wenn sie vom gleichen Team (im weiteren Sinne) wie die Software erstellt / vertrieben werden. Kurse von Drittanbietern sind keine Dokumente.

— Donal Fellows

Natürlich sind sie. Dokumentation von Drittanbietern ist Dokumentation, auch wenn sie nicht unter Ihrer Kontrolle steht (und nicht in Ihrer Verantwortung zu produzieren liegt): Sie dient dem Ziel des Lesers, das Material zu erklären. Wenn es für Sie ein Problem ist, dass Personen Dokumente schreiben, die nicht unter Ihrer Kontrolle stehen, sollten Sie die Notwendigkeit dieser Dokumentation vermeiden.

2

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.

— DXM
quelle

Zu sagen, dass ich den falschen Teil des Gesprächs aufgrund eines einzelnen Q genommen habe, ist ein wenig eine Schlussfolgerung, die ich aus einem Q ziehen kann :) Ich bin neu in diesem Unternehmen und helfe bei Verbesserungen. Es ist etwas schwierig, die Anzahl unserer Kunden in den über 10.000 Entwicklern (wir schreiben Datenbanken) anzugeben, mit denen wir alle verhandeln (obwohl ich mich bemühe, Fokusgruppen, Beratungsgremien usw. zu leiten). Ich bin mit Ihrer Antwort nicht einverstanden, aber ich habe nur gesucht, was Dokumentation für diesen einen Teil der Konversation sein könnte / nicht, damit ich einen Datenpunkt haben kann, von dem aus ich anfangen kann, nicht nur meine eigene Meinung.

— Dan McGrath

@DanMcGrath: Tut mir leid, ich neige dazu, PMs zu reiben, einschließlich meiner eigenen, auf die falsche Weise :) Ungeachtet der angenommenen Schlussfolgerung, die ich aus Ihrem Q gezogen habe, würde ich immer noch behaupten, dass "alles", was mit dem Code einhergeht, in Betracht gezogen werden kann "Dokumentation". Wenn ich Sie wäre, würde ich, anstatt zu fragen, was Dokumentation sein kann, und eine umfassende Liste aller Arten von Dingen zusammenstellen (ich hatte früher eine Referenzserviette mit einem UML-Diagramm darauf), zu meinem Kundenstamm zurückkehren und fragen ihnen, was sie brauchen. Wenn niemand sagt "Ich möchte ein Video-Tutorial", warum sollte ich überhaupt irgendwelche Gehirnzyklen damit verbringen, dies zu berücksichtigen?

— DXM

Kein Problem DXM. Ich bin auch nur eine neue PM und rasiere erst kürzlich meine Codierungskürzel (teilweise) ab. Ich war mehr daran interessiert zu sehen, ob jemand mit etwas zurückkam, das ich weder als Konzept noch als Artefakt in Betracht gezogen hatte. Ich bin ein großer Fan davon, zu fragen, was Ihr Problem ist, und unser Team es gemeinsam mit den Kunden erarbeiten zu lassen, anstatt zu fragen, was wir tun sollen. In der gleichen Richtung wie ['Wir wollen schneller sein' -> Wir bauen Autos] gegen ['Wir wollen, dass du uns schnellere Pferde gibst']. Wenn Sie uns viele Informationen zur Hand haben, können Sie mit größerer Wahrscheinlichkeit gemeinsam die beste Lösung finden.

— Dan McGrath

2

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.

— Mücke
quelle

2

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.

— John Bode
quelle