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

TL: DR? Schön hier:

Gibt es, abgesehen von der Einstellung oder Auslagerung an einen technischen Redakteur, grundlegende Standards / Konventionen / Praktiken, die technische Redakteure in ihrem Fach anwenden, um daraus eine ordnungsgemäße IT-Dokumentation zu erstellen und diese Dokumentation im Laufe der Zeit zu pflegen?

Beim Schreiben verschiedener Dokumentationen sowohl für die interne IT-Nutzung als auch für die externe Nutzung durch unsere Mitarbeiter wurde deutlich, dass unsere Mitarbeiter alle ihren eigenen Stil in Bezug auf die Dokumentation haben.

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

Dem eigentlichen Verfassen von IT-Dokumenten fehlt jedoch immer noch eine echte Konvention / ein Standard. Einige verwenden Tools von Drittanbietern wie ScreenSteps, andere verwenden einfach Word und erstellen eine einfache Gliederung wie:

1. Öffnen app
2. Klicken Sie auf "Start Global Thermonuclear War".
3. ...
4. Profitieren

Die interne IT-Dokumentation ist tatsächlich schlechter , basierend auf dem, was der Mitarbeiter oder Berater zu diesem Zeitpunkt für ausreichend hielt, um entweder seine eigenen Erinnerungen festzuhalten, oder auf dem Editor seiner Wahl (vi, word, excel, powerpoint, serviette, internes Wiki). Das Problem tritt auf, wenn ein Mitarbeiter das Unternehmen verlässt oder sich im Urlaub befindet und versucht wird, selbst grundlegende Informationen herauszufinden. Manchmal ist nur das Dateidatum ein Indikator dafür, ob die Daten noch relevant sind oder nicht.

Eine einfache Übersicht, aktuelle Screenshots oder sogar vollständige HD-Videos sind zwar gut und schön, aber wir haben keinen tatsächlichen technischen IT-Redakteur und können nicht anders, als zu glauben, dass uns in diesem Bereich etwas fehlt.

Können wir unsere eigenen Standards für unsere Dokumentation zusammen mit genehmigten Vorlagen erstellen? Ja, aber warum das Rad neu erfinden? Wenn solche Standards und Konventionen bereits in der "Gilde" des Technischen Redakteurs existieren, sollten wir diese Konventionen besser befolgen, damit unsere Dokumentation klar, präzise und professionell ist.

Um zu vermeiden , wird gesagt, „ Google es “ , ich habe Blick auf Websites , die einige Formatierung Praktiken zeigten und während dieser SF Q: IT Dokumentation Plattformen hilft mit Plattformen und Software zu finden , die Schrift zu behandeln, ist es nicht zu diskutieren , ob es wirklich sind Standards in die Branche.

Gibt es, abgesehen von der Einstellung oder Auslagerung an einen technischen Redakteur, grundlegende Standards / Konventionen / Praktiken, die technische Redakteure in ihrem Fach anwenden, um daraus eine ordnungsgemäße IT-Dokumentation zu erstellen und diese Dokumentation im Laufe der Zeit zu pflegen?

Schreiben ist eine Disziplin.

Ich habe viel getan , und ich habe so viele Grundlagen, wie eine ungeübte Person bekommen kann, ohne dass Dokumentation ein oberster Teil meiner Arbeit ist. Die Zeit hat mir gezeigt, welche Dokumentation, die ich produziere, tatsächlich gelesen wird und was im Regal von Eternal TL; DR steht. Dies ist in der Tat die Regel Nummer eins, wenn man etwas schreibt:

Kenne deine Zuhörer.

Das Publikum für die interne IT-Dokumentation sind wir. Und Systemadministratoren? Wenn wir nach Dokumentation greifen, insbesondere nach interner Dokumentation, suchen wir nach:

• Auffindbar
• Kurz
• Auf den Punkt
• Bringt mich dahin, wohin ich gehe

Die Erklärung mit fünf Absätzen im Hintergrund für ein System wird zugunsten der Checkliste darunter ignoriert, da wir es eilig haben und es nur erledigen müssen. Und wenn die Warnung darin, dass, wenn Sie bestimmte Schritte außerhalb der Reihenfolge ausführen, alle Ihre Sicherungen gelöscht werden, sich in diesem übersprungenen Textblock befindet, sollte möglicherweise eine aufmerksamkeitsstarke Formatierung vorhanden sein, oder das Bit in das Textelement aufnehmen Checkliste auch.

Prozessdokumentation

Bei dieser Art von Dokumentation geht es darum, eine Vorgehensweise zu beschreiben. Es ist für eine ungeübte Person am einfachsten zu produzieren, da es meistens nur eine Reihe von Schritten aufschreibt, die befolgt werden müssen. Nach meiner Erfahrung weist eine gute Prozessdokumentation folgende Merkmale auf:

• Enthält eine Checkliste.
• Die Checkliste befindet sich auf derselben Seite wie 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, das die Theorie hinter der Checkliste und mögliche Abweichungen beschreibt.

Sie möchten, dass die Checkliste befolgt wird und mindestens die ersten Schritte zur Fehlerbehebung bereits auf der Seite (oder nur einen Klick entfernt) vorhanden sind, falls diese erforderlich sind.

Dies ist ein bekanntes Format, wenn Sie sich jemals Microsoft KB-Artikel angesehen haben: Zusammenfassung, Korrektur, Details, betroffene Systeme. Dafür gibt es einen Grund.

Anleitungen zur Fehlerbehebung

Dies ist schwieriger als die Prozessdokumentation, da Sie Entscheidungsbäume in Ihre Dokumentation kodieren 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:

• Seien Sie kurz, ertrinken Sie Ihren Leser nicht im Detail.
• Machen Sie sich klar, wo die Entscheidungspunkte liegen und wo Folgemaßnahmen ergriffen werden müssen.
• Speichern Sie die technischen Hintergrundinformationen für die Architekturdokumentation.

Eine Anleitung zur Fehlerbehebung kann eine große Geschichte von Choose Your Own Adventure sein oder eine große Liste mit Aufzählungszeichen von allem, was mit einem System schief gelaufen ist und was es behoben hat.

Architekturdokumentation

Der am schwersten zu produzierende Typ, da er als Referenzmaterial konzipiert ist, auf das immer nur neue Leute verweisen, die ihre Köpfe um dieses komplexe Ding wickeln möchten, in das sie gerade hineingegangen sind.

Architekturdokumentation ist das Warum-Dokument. Deshalb wird dieses System verwendet und nicht dieses System, wie sie mit diesem anderen System verbunden sind und warum diese Verbindung so funktioniert hat, wie sie funktioniert hat. Dies ist die Dokumentation, die Sie schreiben sollten, sobald Sie wissen, wie Ihre Produktionskonfiguration aussieht, und die aktualisiert wird, sobald Änderungen vorgenommen werden.

In Bezug auf das Format muss ich mich an die Experten wenden.

Gute Dokumentation ist auch mehr als nur die Vorlage und das Format für sie. Ein einheitliches Erscheinungsbild ist gut und verbessert die Lesbarkeit. Außerdem sind einige andere Dinge erforderlich.

Regelmäßige Updates

Gewöhnen Sie sich an, die Dokumentation durchzugehen, die Sie bereits benötigen, um sicherzustellen, dass sie noch gut ist. Die Checkliste für Version 1.17 ist möglicherweise nicht für Version 1.26 geeignet. Rote Checklisten müssen am meisten aktualisiert werden, da selbst die kleinsten Änderungen an der Benutzeroberfläche das Ganze zunichte machen können.

Wenn Sie 10 Minuten pro Woche darauf verwenden, die Dokumentation durchzugehen und Dinge zu identifizieren, die bereinigt werden müssen, kann dies erstaunliche Dinge bewirken .

Die Architekturdokumentation muss regelmäßig von jemandem überprüft werden, der das System kennt. Wie bereits erwähnt, handelt es sich um selten verwendete Dokumente, die jedoch sehr nützlich sind, wenn Sie sie tatsächlich benötigen. Sie möchten nicht, dass das Dokument beschreibt, wie der Print-Serving-Cluster des Campus mit NetWare verbunden ist, als die Migration zu Windows vor drei Jahren erfolgte.

Auffindbar

Dies ist am schwierigsten zu beheben, da es zu einem großen Teil davon abhängt, wo Sie Ihre Dokumentation speichern.

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

Was hast du schon versucht?

In Kürze gefolgt von

Der Top-Hit bei Google löst Ihr Problem. Vielleicht solltest du das versuchen.

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

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

Wenn Sie mit einem Dokumentrepository arbeiten, das Tags unterstützt, standardisieren Sie Ihre Tags . Schauen Sie sich einfach irgendwann die ServerFault-Tag-Liste an, um herauszufinden, warum. Benutzer sollten sich die acht Permutationen von nicht merken müssenVMwarenur um das Zeug zu finden, nach dem sie suchen. Dies erfordert gelegentliche Retagging-Bemühungen.