Passendes Konzept für eine Anwenderdokumentation

[Aurelius]

Hallo DPler

In unserem Unternehmen soll in nächster Zeit ein neues Konzept für das Bereitstellen/Erstellen von Anwenderdokumentationen entwickelt werden, wobei folgende Dinge beachtet werden sollten:

• das Programm besteht aus mehreren Modulen, welche zu- sowie abschaltbar sein können
• für viele Kunden sind spezielle Anpassungen in den jeweiligen Modulen durchgeführt worden, so dass neben der "Standarddokumentation" auch kundenspezifische Dokumente möglich sein müssen.
• Single-Source-Publishing, sprich aus einer Datenquelle können die Print- sowie weitere Foramte wie Onlinehilfen erstellt werden
• Versionshistorie
• Zugriffsrechte für Autoren (nicht so wichtig, und wenn dann auch eher bei Wiki, DMS etc)
• Unterstützen mehrerer Ausgabesprachen (nice-to-have)

Aus diesen Vorgaben lässt sich schließen, dass ein einfaches Verfassen in einem Texteditor wie bspw. Word zwar durchaus möglich, aber nicht sehr effizient ist. Für solche Anforderungen exisiteren auf dem Markt diverse Lösungen (DMS, TMS, Wiki usw.), allerdings gestaltet sich die Suche nach einem passenden nicht gerade einfach

Daher wollte ich einfach mal fragen, wie ihr bzw. eure Unternehmen solche Dokumentationen organisieren/erstellen und was für Werkzeuge dabei eingesetzt werden.

[Bernhard Geyer]

Zitat von Aurelius:

• das Programm besteht aus mehreren Modulen, welche zu- sowie abschaltbar sein können. Demntsprechend muss auch die Dokumentation flexibel sein

Wieso das? Bei uns ist in der Doku alles drin. Module die Lizenztechnisch freigeschaltet werden, werden entsprechend in der Doku gekennzeichnet.

[Uwe Raabe]

Ich benutze Help & Manual in der professional Variante.

- Module: es gibt dort u.a. die Möglichkeit einzelne Teile bei der Ausgabe zu unterdrücken (oder einzuschließen - je nach Standpunkt).
- Bei der kundenspezifischen Doku bin ich mir nicht sicher, wie man das am besten löst, aber die Community ist sehr rege und hilfreich.
- Single-Source-Publishing: hier ist der Name Programm
- Versionshistorie: das Projekt besteht aus XML-Dateien, die sich mit jedem VCS bequem verwalten lassen
- Zugriffsrechte: kann ich nichts zu sagen -> Community
- Mehrsprachigkeit: unterschiedlich-sprachige Dokus sind untereinander verlinkt, so daß Änderungen am Original leicht in den anderen Sprachen darstellbar sind.

[Sybok Factor]

Ich kann Uwe da nur zustimmen. Help & Manual ist vergleichsweise günstig und leicht zu bedienen. Ich habe vor zwei Jahren verschiedene Tools verglichen, an zweiter Stelle wäre Author-it gekommen, ist aber sehr teuer und konnte unser bestehendes Handbuch nicht importieren.

Für Help & Manual spricht außerdem: Ist in DELPHI geschrieben!

Viele Grüße
Sybok Factor

[Aurelius]

@ Bernhard: Ist eigentlich ein guter Einwand, daher habe ich den Teil erst einmal rausgenommen. Bei Bedarf sollte soetwas, wenn es dann doch benötigt wird, relativ einfach zu bewerkstelligen sein.

[Aurelius]

Ein kleiner Push

[Aurelius]

Und nochmal ein letztes Schubserchen.

Software der DPler scheint so gut zu sein, die benötigen keine Doku

[mkinzler]

Ich lasse die Doku immer von den Anwendern erstellen ( sind interne Anwendungen)

[Dezipaitor]

Anwenderdokumentation entsteht aus der Spezifikation, u.a. den Anwendungsfällen.
Schau dir am Besten viele verschiedene Dokus, z.B. u.a. http://confiss.org (Mitwirkender)

Weiterhin muss man sagen, dass viele Handbücher garnicht gelesen werden. Manchmal ist es daher besser, (zusätzlich) eine Art Wissensdatenbank aufzubauen (oder FAQ) und zu propagieren, wo der Anwender gezielt suchen kann.
Weiterhin sollten Begriffe definiert werden (meist bereits in der Spezifikation gemacht), damit Anwender und Hersteller über dasselbe Thema reden.
Auch wichtig ist, dass der Schriftstil nicht zu kompliziert oder zu einfach gehalten wird, da dadurch die Anwender den Inhalt schlechter verstehen.
Und letztendlich ist es sehr wichtig, die Dokumentation auch am Anwender zu testen, um zu sehen, wo Nachbesserungsbedarf besteht.

Meine Liste ist nur eine Aufzählung und ist sicherlich nicht vollständig oder der Weisheit letzter Schluss.

[Ralf Meyer]

Hi,

wir haben es folgendermaßen gelöst:
Wir haben eine Hilfe-Anwendung erstellt, die die Hilfetexte in der eigenen Datenbank speichert.
Intern werden ein ID-String bestehend aus Fenster, Komponentenname und Sprachkürzel als eindeutige Referenz herangezogen.

Die Hilfe selber besteht aus einem Kurztext und einem Langtext und einem Kommentarfeld.
Der Kurztext dient in der Ansicht als Orientierung.
Der Langtext wird als RTF in der abgespeichert und kann somit auch mit Bildern und Links versehen werden.

In der Anwendung wir über den zentral registrierten HotKey F1 die Hilfe zum Fenster aufgerufen. Strg+F1 ruf die Hilfe zu der aktiven Komponente auf.

Je nach Angemeldetem Benutzer kann dieser die Hilfe nur lesen, Kommentieren oder als Redakteur über den bereitgestellten RTF-Editor selber erweitern.
Es wird natürlich auch die Sprache übergeben, so das jedes Thema auch in der entsprechenden Sprache des Beutzers angezeigt bzw. bearbeitet werden kann.

Bei uns wird die Hilfe rege benutzt. Unsere Redakteure sehen aus den Kommentaren die der versierte User schreiben darf, was die User sich zusätzlich aufschreiben um den Programpunkt zu verstehen. Die gehen dann hin, und ziehen ihre Infos da raus um die Hilfe zu verbessern.

Somit haben wir ein lebendes System welches auch vom Anwender akzeptiert wird.

Gruß
Ralf