Handbücher - Wie aktuell?

10

Wenn Sie ein Produkt haben, das schon lange auf dem Markt ist, sich aber täglich noch in der aktiven Entwicklung befindet - wie oft sollten die Handbücher aktualisiert werden? Wenn Ihre Benutzer aufgrund der Tatsache, dass Ihre Organisation es für richtig hält, ständig auf die neueste Version aktualisiert werden, sind die neuesten Fehlerkorrekturen immer in der ausgelieferten Version enthalten. Das heißt, Sie könnten einen Fehler an einem Tag beheben und am nächsten Tag wird die Produktion beeinträchtigt.

Brian
quelle
1
Sprechen wir über gedruckte oder Online-Handbücher? Es gibt mindestens ein paar verschiedene Formen, die dies annehmen kann.
JB King
Online (PDF) Handbücher
Brian

Antworten:

4

Ich würde das Handbuch aktualisieren:

  1. Für jede Hauptversion und
  2. Wenn wichtige neue Funktionen stabil und ausgereift genug sind, dass Sie wissen, dass sie sich nicht alle fünf Minuten ändern werden.
Robert Harvey
quelle
3

Aktualisieren Sie das (PDF-) Handbuch jedes Mal, wenn eine Codeänderung die Anweisungen im Handbuch ändern würde. Aktualisieren Sie das Handbuch einfach als Teil des Freigabeprozesses

Wenn sich die Benutzer auf das Handbuch verlassen, um zu erfahren, wie das Produkt verwendet wird, und sich das Produkt ändert, ist es nur normal, dass sich auch die relevanten Abschnitte des Handbuchs ändern sollten

Steven A. Lowe
quelle
1
Wenn also kein technischer Redakteur angestellt ist, aktualisieren Sie es selbst?
Brian
@ 0A0D - Wenn Sie keinen Autor haben, haben Sie keine große Auswahl, es sei denn, es gibt Test- oder Supportmitarbeiter, die dies tun können.
JeffO
1
Ich habe das Dokument 'Quelldateien' als Teil meiner Projekte. Sie werden immer gleichzeitig mit dem Code aktualisiert. Sie werden mit Releases versioniert und mit denselben Quell-Managmnet-Tools wie die übrigen Projektdateien verwaltet (gehen Sie zu Mercurial!). Ich habe einen ziemlich standardmäßigen Satz von Handbüchern für ein Projekt und diese werden alle auf die gleiche Weise verwaltet (Benutzerhandbuch, Konfigurations- / Installationshandbuch, Versionshinweise und unsere eigenen technischen Referenz- / Spezifikationsdokumente).
2

Beziehen wir uns 2010 noch auf gedruckte Dokumentation? Warum? ;)

In aller Ernsthaftigkeit sollte die Dokumentation (entweder "F1" -Anwendungshilfe, PDF oder Online-Dokumentation) Teil jeder einzelnen Version sein. Keine Ausreden. So einfach ist das "Veröffentlichen". Tatsächlich gibt es, IMO, keine Entschuldigung dafür, die Dokumentation auch zwischen den Veröffentlichungen nicht regelmäßig (online und PDF) zu aktualisieren, sobald Probleme bekannt und behoben sind. Es braucht nicht das gleiche Maß an Qualitätssicherung - nicht einmal in der Nähe.

Mark Freedman
quelle
2

Ich gehe davon aus, dass Sie über Endbenutzerdokumentation sprechen. Das Schreiben von Dokumentation ist ein Problem, und obwohl ich eine Technik entwickelt habe, um mich von der Umkehrung zu überzeugen, habe ich immer noch Probleme damit. So versuche ich es zu verwalten:

Integrieren Sie die Aktualisierung der Dokumentation in Ihr DoD ( Definition von erledigt )

Dadurch wird sichergestellt, dass Ihre Dokumentation am Ende jeder Fertigstellung der User Story auf dem neuesten Stand ist.

Hier ist die Definition von erledigt, die wir geschrieben haben. Ich habe versucht, die Originalformatierungen beizubehalten, damit Sie auf die Idee kommen. Es ist eine A4-Seite, die auf das Whiteboard gelegt wird.

---------- 8 <------------ Hier schneiden ------------ 8 <----------

Das ist nicht verhandelbar

Definition von "Fertig"

  • Code mit 80% Unit-Test-Abdeckung, festgeschrieben im Repository

  • Screenshots, falls zutreffend (1024 x 728, 395 x 281, 170 x 121 und 729 x 329)

  • Funktionsbeschreibungen, falls zutreffend (50 Zeichen, 100 Zeichen)

  • Vollständige Dokumentation für Endbenutzer

  • Was ist neue Datei richtig aktualisiert

---------- 8 <------------ Hier schneiden ------------ 8 <----------

Natürlich können Sie der Dokumentation einen Überprüfungsprozess hinzufügen. Wir haben das, da keiner von uns englische Muttersprachler ist.

Einer der Vorteile der Definition von Done wie dieser besteht darin, dass Ihr Produkt möglicherweise am Ende jeder Fertigstellung der User Story ausgeliefert werden kann.

Verwenden Sie diese Technik in Kombination mit dieser .


quelle
1

In meiner Organisation gibt es normalerweise drei Arten von Veröffentlichungen:

  1. Engineering Release - im Grunde ein Hotfix für einen bestimmten Kunden oder eine Funktion, die nur ein bestimmter Kunde sofort angefordert hat.
  2. Minor Release - Fehlerbehebungen, inkrementelle Unterstützung
  3. Hauptversion - Unterstützung für neue Funktionen usw.

Per Definition muss in Major Release die entsprechende Dokumentation sowohl online als auch offline vorhanden sein. Unser Tracking-System stellt sicher, dass die Dokumentation ein wesentlicher Bestandteil der Checkliste ist.

Kleinere Releases benötigen nur Dokumentation zu neuen Inhalten, die auf der Ebene der Benutzerwahrnehmung hinzugefügt wurden. Wenn Sie also eine weitere Heuristik eingefügt haben, die die Zeitkomplexität in bestimmten Szenarien verringern kann, kann es ein wichtiger Aufruf sein, sie in das PDF aufzunehmen.

Engineering-Releases könnten ohne Dokumentation auskommen. Einige informelle Verwendungshinweise sollten gut genug sein, um loszulegen.

Fanatic23
quelle
0

Die Dokumentation sollte mit der Software synchronisiert sein, die Sie an einen Kunden senden. Jede andere Fehlanpassung wird Ihnen Probleme bereiten. Und wenn Sie keinen Schriftsteller im Personal haben, versuchen Sie es mit Auftragnehmern. Wenn Sie einen gefunden haben, den Sie mögen, behalten Sie ihn bei.

SnoopDougieDoug
quelle