(Gekürzte Übertragung des Artikel »Top 10 signs that documentation is craptacular« von Sarah O’Keefe, Scriptorium)
Es gibt eine Menge wirklich schrecklicher technischer Dokumentation draußen in der Welt. Sie ist inkohärent, nicht hilfreich und/oder hässlich. Die Inhalte wurden „geschrieben“ ohne auf grundlegende Prinzipien der technischen Kommunikation zu achten. Wenn sie mit Inhalten dieser Art konfrontiert sind, ist es wahrscheinlich nicht sinnvoll, die Implementierung eines superschlauen neuen Systems zu versuchen. Konzentrieren Sie sich stattdessen darauf, die Redaktion Schritt für Schritt vorwärts zu bewegen.
Hier sind die Top 10 der Anzeichen dafür, dass eine Dokumentation Müll ist:
10. Die Dokumentation enthält freiwillig mehr als eines der folgenden Dinge: Lose-Blatt-Sammlung, Änderungsseiten, Liste gültiger Seiten oder nummerierte Überschriften.
9. Es gibt keinen Redaktionsleitfaden.
8. Es gibt kein Template; oder gibt es ein Template, dem niemand folgt.
7. Die technischen Redakteure haben keine Fachkenntnisse.
6. Der technische Support weist Anrufer darauf hin, die Dokumentation zu ignorieren.
5. Der Zeitaufwand fürs Schreiben ist ungefähr so hoch wie der Aufwand für die Formatierung.
4. Die einzige elektronische Version der Dokumentation ist eine PDF-Datei.
3. In der HTML-Version der Dokumentation werden die Tabellen als Grafiken eingebunden, um „das ursprünglichen Erscheinungsbild zu erhalten“.
2. Es gibt keinen Index; oder der Index ist unbrauchbar.
1. Die Online-Version der Dokumentation widerspricht der Druckversion der Dokumentation.
Wenn schlechte Dokumentation festgestellt wurde, muss als erstes das Bewusstsein schaffen werden, dass gute Inhalte wertvoll für die Firma sind. Der genaue Business Case ist firmenspezifisch, aber einige allgemeine Wertversprechen sind:
- Gute Dokumentation reduziert Kosten für Kundenbetreuung (in der Regel durch eine Verringerung der Menge der Anrufe beim technischen Support).
- Gute Dokumentation erhöht die Kundenzufriedenheit.
- Gute Dokumentation ist für die Einhaltung gesetzlicher Vorschriften erforderlich.
Es gibt wohl einige leicht erreichbare Ziele, die schnell angegangen werden können:
- Erstellen Sie ein attraktives Template für Ihre Dokumentation
- Alle Autoren müssen das Template nutzen
- Implementieren Sie Single Sourcing für Inhalte, die identisch sein sollten
- Erstellen Sie eine nützliche elektronische Version Ihrer Inhalte (in der Regel etwas HTML-basiertes)
- Erstellen Sie einen nützlichen, gut bearbeiteten Index
Falls Sie bei diesen Schritten Hilfe benötigen, wissen Sie wo Sie Hilfe bekommen können. Nicht nur, aber auch bei Scriptorium Publishing.
Haha. Es fehlt noch ein Punkt: die Redakteure haben gar kein Konzept, warum und wie sie eigentlich die blöde Maschine überhaupt dokumentieren sollen…
Das mit den nummerierten Überschriften wurde schon vor 20 Jahren bei meinem damaligen Arbeitgeber als kultureller Unterschied US-DE identifiziert.
Ansonsten braucht es auch in vielen Firmen das Bewusstsein, dass die mit der Entwicklung und dem Kundenmanagement befassten Personen die Dokumentation ernster nehmen sollen.
Es ist Montag und vielleicht bin ich noch nicht wirklich geistig wach genug, und ich mag auch Eulen, aber: Warum ist da ein Bild einer Eule?
@Inge: Die Eule ist das Markenzeichen vom Scriptorium-Blog, der Quelle des Original-Posts.
Huch, 4. (einzige elektronische form ist PDF) – mehr will aber der kunde nicht. Er macht daraus notfallmässig papier. Im PDF kann in die diagramme und zeichnungen hinein gezoomt werden, die querverweise etc sind links. Wo ist da das böse ende?
Und 2. (es gibt keinen index) trifft für fast alles zu, was ich bisher für kunden fabriziert habe. Die sachen sind aber maximal 200 seiten lang.
Ber wenigstens komme ich bei den numerierten überschriften kein fett weg: Wenn der kunde nichts merkt, sind die überschriften nicht numeriert – viele wollens aber so: am tel ist es einfacher auf 3.5.7 zu verweisen als auf „…“ auf seite 77.
Ja ja Top Ten… Das erhöht zumindest die Aufmerksamkeit auf den Urheber.
Anyway, entscheidend ist: Was will der Kunde? Welches Leseverhalten hat er? Welche Prioritäten setzt er?
Wer ist meine Zielgruppe?
Damit keine Mißverständnisse aufkommen… folgende Aspekte sind ohne Frage bedeutend und wichtig, Zitat:
Es ist sehr interessant, die unterschiedlichen Reaktionen aus dem Englisch- und Deutschsprachigen Lesepublikum zu sehen.
PDF ist natürlich als Druckmethode gut geeignet. Für echte Onlinehilfe braucht man aber etwas in der HTML-Familie.
Ich verstehe (leider) ganz gut, das Kundenprioritäten und Einschränkungen in der Doku-Qualität klar abgebildet werden.
Meine Perspektive ist in diesem Artikel als Dienstleisterin, die ganz regelmaßig gefragt wird: „Wie können wir unsere Redaktion verbessern? Was fehlt in unserer Doku?“
Hallo Frau O’Keefe,
Sie schreiben/sprechen sehr gut deutsch – Respekt!
Ich verstehe zu gut, dass sie mit den Top 10 „aufrütteln“ wollen. Es ist unbedingt notwendig.
Vermutlich stimmen Ihnen sehr viele Redakteure zu, aber nur wenige ändern nachhaltig etwas am Istzustand.
Sie wählen das Verb „konfrontieren“. Nach der Implementierung eines neues Systems, z.B. CMS, wird dann eine „neue Front“ eröffnet. 😉
Der erste Titel war „The Asset Assertion“ d.h. „Die Gewinnbehauptung“ (?? klingt auf Deutsch nicht besonders gut) also diese Idee, das Information in einem Unternehmen Wert hat. Davon kam ich ganz einfach auf die Top Ten-Liste, wo man sieht, dass technische Information manchmal nicht besonders wertvoll ist.
(Als Kind wohnte ich viele Jahre in Deutschland. Mein XML-Wortkenntnis ist auf Deutsch ziemlich begrenzt.)