Wie erstelle ich bessere Benutzerhandbücher?

[mf_2]

ANZEIGE

Hallo zusammen,

ich muss hin und wieder Benutzerhandbücher für eigene Erweiterungen bestimmter Softwareprogramme schreiben - so auch heute.
Bisher schreibe ich die einfach immer in Word runter, Deckblatt mit Titel und Version auf die erste Seite, Inhaltsverzeichnis auf die zweite Seite, kurzes Abstract vor die eigentliche Doku und fertig.
Dieses Mal möchte ich es aber anders machen und frage ich mich aber, wie es die Profis machen. Ich werde vermutlich von der Struktur her nie mit darauf spezialisierten Firmen mithalten können, aber das ist auch nicht der Anspruch.
Aber es gibt sicher viele Abstufungen zwischen einem durch eine spezielle Redaktion erstellten Benutzerhandbuch und dem, was ich aktuell fabriziere.
Gibt es Ratgeber und/oder Webseiten, die einem hier Wissen an die Hand geben können?
Darauf aufbauend: Gibt es kommerziell nutzbare Formatvorlagen für Microsoft Word, welche die wichtigsten Bausteine schon einmal mitbringen?

Konkret geht es mir um folgende Dinge:

• Allgemeiner Aufbau des Dokuments
• Aufbau der Kapitel zur Beschreibung eines Vorgangs (Klickanleitung)
• Wie erstelle ich gute Screenshots (einfach einfügen, oder besser mit Pfeilen, Highlighting etc. arbeiten?)?
• Wie stelle ich Mausklicks (links, rechts, doppelt) dar?
• Meine Anwender sind IT-Mitarbeiter in Deutschland, USA, China, Indien -> muss ich ein Handbuch, welches sich beispielweise an Inder/Amerikaner/Chinesen richtet, strukturell anders aufbauen als eines für Deutsche (abgesehen von Letter vs. A4)?

Ich erwarte nicht die Lösung auf dem Silbertablett - eine Literaturempfehlung hierzu wäre auch schon ein guter Startpunkt.
Eine Google-Recherche findet diverse Formatvorlagen - aber ich als Laie kann nicht beurteilen, welche dieser Vorlagen meine Anwenderschaft anspricht.

Habt ihr Ideen?

Viele Grüße
mf_2

 

[red_travels]

Ich versuche mich beim Aufbau meiner Anwenderdokus immer an die Anleitungen der SAP-Fachbücher zu halten. Also auch mal mit kleineren Screenshots, die auf das Detail eingehen im Text arbeiten.

Ansonsten eben eine Step-By-Step Anleitung, die auf alle erdenklichen Fälle und Fehler (mit Lösungsbeschreibung) eingeht

 

[LH88]

Ich kann nur sagen das ich selbst an den professionellsten Handbüchern scheitere und meisten Hilfe in Online Communities finde, auch mein Steuerberater hat mir letztens erzählt das er ohne seine "Datev Gruppe" aufgeschmissen wäre.

 

[Hauptmann Fuchs]

So etwas erstellt man doch in Markdown, eventuell passendes Template in Hugo oder Jekyll -> HTML -> PDF, fertig.

 

[els]

Wie willst du das ganze publizieren? Gedruckt als Buch, als eBook, als PDF zum teilen, als Webseite?

Wie sieht dein Geschäftsmodell aus? Bist du fest angestellt im gleichen Unternehmen wie die Anwender, wirst du einmalig zur Software-Entwicklung bezahlt oder willst du langfristig am Support mitverdienen?

 

[mf_2]

Ich versuche mich beim Aufbau meiner Anwenderdokus immer an die Anleitungen der SAP-Fachbücher zu halten. Also auch mal mit kleineren Screenshots, die auf das Detail eingehen im Text arbeiten.

Ansonsten eben eine Step-By-Step Anleitung, die auf alle erdenklichen Fälle und Fehler (mit Lösungsbeschreibung) eingeht

Ich nutze auch Screenshots (mit Highlighting der relevanten Stellen bzw. Durchnummerierung via Greenshot). Das mit den Fehlerfällen mache ich auch als Schritt-Für-Schritt Anleitung. Nur weiß ich eben nicht, ob die Form, in der ich das aktuell präsentiere, die ideale ist.

Ich kann nur sagen das ich selbst an den professionellsten Handbüchern scheitere und meisten Hilfe in Online Communities finde, auch mein Steuerberater hat mir letztens erzählt das er ohne seine "Datev Gruppe" aufgeschmissen wäre.

Da ich Individualsoftware erweitere, gibt es dazu leider keine Communities.

So etwas erstellt man doch in Markdown, eventuell passendes Template in Hugo oder Jekyll -> HTML -> PDF, fertig.

Markdown kenne ich von Trello (nutzen wir zur Sprintplanung im Team). Hugo und Jekyll sagen mir nichts, sehe ich mir aber an. Vielen Dank!

Wie willst du das ganze publizieren? Gedruckt als Buch, als eBook, als PDF zum teilen, als Webseite?

Wie sieht dein Geschäftsmodell aus? Bist du fest angestellt im gleichen Unternehmen wie die Anwender, wirst du einmalig zur Software-Entwicklung bezahlt oder willst du langfristig am Support mitverdienen?

Das ganze soll ein eBook für die Anwender sein (PDF). Ich bin Dienstleister der Anwender, der zur Anpassung der Software bezahlt wird. Den Anwendern zeige ich in Schulungen, wie sie die Anpassungen nutzen können. Die PDF hätte den Charme, dass sie die Szenarien dort nachschlagen können und dass es eine Unterstützung für diejenigen ist, die ggf. nicht so gut Englisch können und das daher in der Schulung (gerade eh nur remote ...) ggf. nicht 100% aufsaugen können. Auch könnten die das PDF an neue Kollegen weitergeben. Es geht mir nicht darum, da möglichst langfristig dran zu verdienen (und deswegen bewusst keine PDF rauszugeben oder so).

 

[red_travels]

Ich nutze auch Screenshots (mit Highlighting der relevanten Stellen bzw. Durchnummerierung via Greenshot). Das mit den Fehlerfällen mache ich auch als Schritt-Für-Schritt Anleitung. Nur weiß ich eben nicht, ob die Form, in der ich das aktuell präsentiere, die ideale ist.

da hilft nur die Anwender zu fragen die perfekte Lösung gibt es für das eh nie

 

[Hauptmann Fuchs]

Markdown kenne ich von Trello (nutzen wir zur Sprintplanung im Team). Hugo und Jekyll sagen mir nichts, sehe ich mir aber an. Vielen Dank!

Na ja, halt wie TeX. Hugo und Jekyll spucken HTML aus, das lässt sich natürlich dann wieder per Script konvertieren (und paginieren) nach PDF. Meine Red Hat Lernbücher (also die von RH selbst) sehen so aus, als wurden sie so erstellt.

 

[els]

Bei dem Anwendungsfall wird mein angedachter Vorschlag dann wahrscheinlich ein bisschen zu kompliziert sein:

1. Webseite mit GhostCMS erstellen.

2. Als Theme DocuHub verwenden.

und ggf.

3. Kommentarbereich mit Talkyard/NodeBB/Disqus/Cove Comments als Community hinzufügen.

GhostCMS hat einen Markdown-Editor wie von Hauptmann Fuchs angesprochen, erlaubt einfache Zugriffsrechteverwaltung mit mehreren Leveln und damit auch eine gute Monetarisierungs-Funktion bei langfristigen Support-Verträgen.
Als Anregung zur Strukturierung einfach mal das verlinkte DocuHub-Beispiel anschauen.

 

[mf_2]

da hilft nur die Anwender zu fragen die perfekte Lösung gibt es für das eh nie

Aktuell geht es um eine Anleitung für die Inder. Wenn ich die frage, ob die Anleitungen bisher immer gepasst haben, dann werden die "ja" sagen. Ich weiß nicht, ob ich aus denen ohne Weiteres auch mal ein "nein" rausbekomme. Deswegen ist fragen schwierig. Ggf. muss ich gezielter fragen, welche Sachen man verbessern kann. Ggf. können die es aber auch selbst gar nicht sagen - oft weiß man ja vllt. gar nicht, dass es besser geht, bis man es einmal gesehen hat. Oder es gibt Arten der Strukturierung, die die Anwender unterbewusst besser ansprechen -> darüber Feedback zu bekommen wird vmtl. auch schwierig. Aber ich werde auf jeden Fall aktiv Feedback einholen - das habe ich bisher tatsächlich zu wenig gemacht.

 

[_AndyAndy_]

Die richtigen Suchbegriffe wären Technische Redaktion und Internationalisierung.

Der Umfang der Automatisierung kommt halt darauf an, ob die Doku ständig fortgeschrieben werden soll und ob das im Team passieren muss.

 

[JFI]

TeX wurde ja bereits erwähnt, schau dir doch mal LaTeX(2e) an:

LaTeX - A document preparation system

LaTeX is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation.

www.latex-project.org

Ist relativ schnell erlernbar, gibt super Dokumentvorlagen und es werden viele Sprachen unterstützt:

LaTeX - A document preparation system

LaTeX is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation.

www.latex-project.org

Auch für PDFs gibt es alles was man braucht, mit dem Paket "hyperref" z.B. kannst du im PDF Links erstellen.

Damit lassen sich typografisch anspruchsvolle Dokumente erstellen, und alles ist logisch strukturiert.

Ein paar weitere nützliche Links:

KOMA-Script Documentation Project | Aktive Anwender verbessern KOMA-Script.

komascript.de

Index of /lshort

tobi.oetiker.ch

Kannst ja mal einen Blick auf lshort.pdf werfen. Ist mit dem hyperref paxkage erstellt.