Gibt es Standards/Konventionen, die von technischen IT-Autoren verwendet werden?

Question

Gut...hier:

Gibt es – abgesehen von der Einstellung oder Auslagerung eines technischen Redakteurs – grundlegende Standards/Konventionen/Praktiken, die Technische Redakteure in ihrem Beruf anwenden und von denen man lernen kann, wie man ordnungsgemäße IT-Dokumentation erstellt und diese Dokumentation im Laufe der Zeit pflegt?

---

Beim Verfassen verschiedener Dokumentationen sowohl für den internen IT-Gebrauch als auch für den externen Gebrauch durch unsere Mitarbeiter ist deutlich geworden, dass jeder unserer Mitarbeiter seinen eigenen Stil hat, was die Dokumentation betrifft.

Ausgehend von unseren Qualitätsdokumenten und kontrollierten Dokumentationen hat die IT verschiedene Vorlagen für SOPs, WIs und verschiedene Formulare für IT-Qualitätsdokumente verwendet. Diese Dokumente sind zwar nicht unbedingt für den täglichen Betrieb innerhalb der IT nützlich, helfen den Mitarbeitern und dem Unternehmen jedoch bei IT-HR-Problemen, Compliance usw. und sind in der Regel gut geschrieben, gut definiert und folgen zumindest den Vorlagen und Dokumentationsstandards der Qualitätsabteilung (wie Versionierung, ECNs usw.).

Für das Verfassen unserer tatsächlichen IT-Dokumente mangelt es jedoch noch immer an einer echten Konvention bzw. einem echten Standard. Einige verwenden Tools von Drittanbietern wie ScreenSteps, andere verwenden einfach Word und erstellen eine einfache Gliederung wie:

1. Offenapp
2. Klicken Sie auf „Globalen thermonuklearen Krieg starten“
3. ...
4. Profitieren

Die interne IT-Dokumentation ist tatsächlich noch schlimmer, basierend auf dem, was der Mitarbeiter oder Berater zu dem Zeitpunkt für ausreichend hielt, um entweder sein eigenes Gedächtnis aufzufrischen oder was auf dem Editor seiner Wahl (vi, Word, Excel, PowerPoint, Serviette, internes Wiki) basierte. Das Problem entsteht, wenn ein Mitarbeiter das Unternehmen verlässt oder im Urlaub ist und man sich verzweifelt bemüht, selbst grundlegende Informationen herauszufinden. Manchmal ist nur das Dateidatum ein Indikator dafür, ob die Daten noch relevant sind oder nicht.

Eine einfache Gliederung, echte Screenshots oder sogar ein komplettes HD-Video sind zwar schön und gut, wir haben jedoch keinen echten technischen IT-Redakteur im Team und sind der Meinung, dass es uns auf diesem Gebiet an Kompetenzen mangelt.

Könnten wir neben genehmigten Vorlagen auch unsere eigenen Standards für unsere Dokumentation festlegen? Ja, aber warum das Rad neu erfinden? Wenn es innerhalb der „Zunft“ der technischen Redakteure bereits solche Standards und Konventionen gibt, wäre es besser, wenn wir diese Konventionen befolgen würden, damit unsere Dokumentation klar, prägnant und professionell ist.

Um zu vermeiden, dass man es Ihnen sagt"Google es", ich habe mir Websites angesehen, die einige Formatierungspraktiken zeigten, und während diese SF-Frage:IT-Dokumentationsplattformenhilft bei der Suche nach Plattformen und Software zum Schreiben, diskutiert jedoch nicht, ob es in der Branche wirklich Standards gibt.

Gibt es – abgesehen von der Einstellung oder Auslagerung eines technischen Redakteurs – grundlegende Standards/Konventionen/Praktiken, die Technische Redakteure in ihrem Beruf anwenden und von denen man lernen kann, wie man ordnungsgemäße IT-Dokumentation erstellt und diese Dokumentation im Laufe der Zeit pflegt?

Answer 1

Schreiben ist eine Disziplin.

Ich habe viel davon gemacht, und ich habe so viele Grundlagen drauf, wie ein Laie nur kann, ohne dass Dokumentation ein wichtiger Teil meiner Arbeit ist. Die Zeit hat mir gezeigt, welche Dokumentation, die ich erstelle, tatsächlich gelesen wird und was auf dem Regal des ewigen TL;DR landet. Dies ist in der Tat die wichtigste Regel beim Schreiben von allem:

Kenne deine Zuhörer.

Die Zielgruppe für interne IT-Dokumentation sind wir selbst. Und Systemadministratoren? Wenn wir nach Dokumentation suchen, insbesondere nach interner Dokumentation, suchen wir nach:

• Lokalisierbar
• Knapp
• Auf den Punkt
• Bringt mich dorthin, wo ich hin will

Die fünf Absätze umfassende Erklärung zum Hintergrund eines Systems wird zugunsten der Checkliste darunter ignoriert, weil wir in Eile sind und es einfach erledigen müssen. Und wenn die Warnung darin, dassWenn Sie bestimmte Schritte in der falschen Reihenfolge ausführen, werden alle Ihre Backups gelöschtsich in diesem übersprungenen Textblock befindet, sollte dieser vielleicht aufmerksamkeitserregend formatiert werden oder dieser Teil sollte auch in die Checkliste aufgenommen werden.

Prozessdokumentation

Bei dieser Art der Dokumentation geht es darum, eine Vorgehensweise zu beschreiben. Sie ist für einen Laien am einfachsten zu erstellen, da es sich dabei meist nur um das Aufschreiben einer Reihe von Schritten handelt, die zu befolgen sind. Meiner Erfahrung nach weist eine gute Prozessdokumentation die folgenden Merkmale auf:

• Enthält eine Checkliste.
• Auf derselben Seite befindet sich die Checkliste sowie eine kurze Zusammenfassung, wann und warum die Checkliste ausgeführt wird.
• Unterhalb der Checkliste oder auf einer verlinkten Seite befindet sich ein längeres Dokument, in dem die Theorie hinter der Checkliste und mögliche Abweichungen beschrieben werden.

Sie möchten, dass eine Checkliste zum Befolgen vorhanden ist und dass zumindest die ersten Schritte zur Fehlerbehebung bereits auf der Seite (oder nur einen Klick entfernt) angezeigt werden, falls diese benötigt werden.

Wenn Sie sich schon einmal Microsoft KB-Artikel angesehen haben, ist Ihnen dieses Format bekannt: Zusammenfassung, Fixit, Details, betroffene Systeme. Dafür gibt es einen Grund.

Anleitungen zur Fehlerbehebung

Dies ist schwieriger als Prozessdokumentation, da Sie Entscheidungsbäume in Ihre Dokumentation einbetten müssen. Eine einfache Checkliste wird wahrscheinlich nicht ausreichen, aber eine verzweigte Checkliste, die Links zu anderen Checklisten verwendet, ist durchaus machbar. Für diese Art von Dokumentation gelten dieselben Regeln wie für Prozessdokumente:

• Fassen Sie sich kurz und überhäufen Sie Ihren Leser nicht mit Einzelheiten.
• Machen Sie sich klar, wo die Entscheidungspunkte liegen und welche Folgemaßnahmen erforderlich sind.
• Heben Sie sich die ausführlicheren technischen Hintergrundinformationen für die Architekturdokumentation auf.

Eine Anleitung zur Fehlerbehebung kann eine große „Choose Your Own Adventure“-Geschichte sein oder eine große Aufzählungsliste aller Systemprobleme und der dazugehörigen Anleitungen zur Fehlerbehebung.

Architekturdokumentation

Dies ist mit Abstand das am schwierigsten zu erstellende Material, da es als Referenzmaterial konzipiert ist und nur von Neulingen herangezogen wird, die sich mit der komplexen Materie, auf die sie gerade gestoßen sind, auseinandersetzen möchten.

Die Architekturdokumentation ist das Warum-Dokument. Darin wird beschrieben, warum dieses System verwendet wird und nicht jenes, wie es mit diesem anderen System verbunden ist und was diese Verbindung so funktionieren ließ, wie sie funktionierte. Es ist die Dokumentation, die Sie schreiben sollten, sobald Sie wissen, wie Ihre Produktionskonfiguration aussieht, und die Sie aktualisieren sollten, wenn Änderungen vorgenommen werden.

Was das Format angeht, muss ich mich in diesem Fall auf die Experten verlassen.

---

Zu einer guten Dokumentation gehört auch mehr als nur eine Vorlage und ein Format. Ein einheitliches Erscheinungsbild ist gut und verbessert die Lesbarkeit, es sind aber auch noch einige andere Dinge erforderlich.

Regelmäßige Updates

Gewöhnen Sie sich an, die vorhandene Dokumentation durchzugehen, um sicherzustellen, dass sie noch gültig ist. Die Checkliste für Version 1.17 ist möglicherweise nicht mehr gültig für Version 1.26. Es ist Zeit, sie zu aktualisieren. Routine-Checklisten müssen am häufigsten aktualisiert werden, da selbst kleinste Änderungen an der Benutzeroberfläche das Ganze durcheinander bringen können.

10 Minuten widmeneine Wochedie Durchsicht der Dokumentation und die Identifizierung von Dingen, die bereinigt werden müssen, können erstaunliche Dinge bewirken.

Die Architekturdokumentation muss regelmäßig von jemandem überprüft werden, der das System kennt. Wie bereits erwähnt, handelt es sich dabei um selten verwendete Dokumente, die aber sehr nützlich sind, wenn Sie sie tatsächlich benötigen. Sie möchten das Dokument nicht, das beschreibt, wie der Campus-Druckercluster mit NetWare verkabelt ist, als die Migration auf Windows vor 3 Jahren stattfand.

Erkennbar

Dies ist am schwierigsten, denn es hängt in hohem Maße davon ab,WoSie speichern Ihre Dokumentation.

Was sagen wir jedem, der mit einer Frage zu ServerFault kommt?

Was haben Sie bereits versucht?

Kurz darauf folgte

Der Top-Treffer bei Google löst dein Problem. Vielleicht solltest du das mal versuchen.

Wir suchen nach unserer Dokumentation, wir gehen nicht zum Bücherregal. Das Dokumentations-Repository muss genauso durchsuchbar sein wie Google, sonst gehen wir stattdessen einfach zu Google.

Das Central Napkin Repository ist ein schlechter Ort für Dokumentationen, zumindest wenn es keinen Online-Index hat (und das wird es nicht). Ein einfaches Wiki ist besser, da die meisten davon zumindest eine grundlegende Textsuche beinhalten. Ein besseres System ist eines, das zusätzlich zum Volltext auch die Suche nach Tags ermöglicht, um die Suche besser auf Zielbereiche zu fokussieren.

Wenn Sie mit einem Dokument-Repository arbeiten, das Tags unterstützt,Standardisieren Sie Ihre Tags. Schauen Sie sich einfach mal die ServerFault-Tagliste an, um zu sehen, warum. Benutzer sollten sich nicht die acht Permutationen vonVMwarenur um das zu finden, wonach sie suchen. Dies erfordert gelegentliches erneutes Taggen.