Ich weiß nicht, ob das Schreiben von Dokumenten in anderen Branchen eine diskussionswürdige Frage ist, aber in der IT-Branche ist dies definitiv eine diskussionswürdige Frage.
In meiner bisherigen Berufserfahrung bin ich oft darauf gestoßen oder habe von anderen gehört, dass sie sich darüber beschwert haben, dass ein bestimmtes System oder eine bestimmte API keine Dokumentation hat, was es schwierig oder sogar unmöglich macht, die Arbeit zu übernehmen.
Da ich mir dieses Problems bereits bewusst bin, werde ich bei meiner Arbeit dem Verfassen von Dokumenten mehr Aufmerksamkeit schenken. Ich versuche, alle Stellen, von denen ich denke, dass sie andere möglicherweise verstehen müssen, in Dokumente zu schreiben, aber ich stelle fest, dass es immer noch viele Probleme gibt. Das werde ich tun Schreiben Sie noch heute eine Notiz, um diese Fragen und meine Meinung festzuhalten.
Lassen Sie mich zunächst direkt auf die von mir beobachteten Probleme eingehen:
- Wie lassen Sie andere wissen, dass Sie eine schriftliche Dokumentation zu einem Problem haben?
- Ist Ihr Dokument für Leser verständlich?
- Wie werden diese Dokumente gepflegt? (Hauptsächlich diese beiden Probleme aktualisieren und verwalten)
- Ist die von Ihnen verfasste Dokumentation notwendig?
Ehrlich gesagt habe ich keine gute Lösung für die oben genannten Probleme, aber ich habe ein wenig von meinen eigenen Gefühlen und Erfahrungen und werde dann die oben genannten Probleme der Reihe nach besprechen.
(Gleichzeitig veröffentlicht auf persönlicher Website: http://panzhixiang.cn/article/2023/2/19/67.html )
Wie lassen Sie andere wissen, dass Sie eine schriftliche Dokumentation zu einem Problem haben?
Unabhängig davon, ob es sich um ein internes Dokument oder ein Dokument im Internet handelt, wird im Allgemeinen niemand das Dokument gründlich lesen, bevor er mit der Arbeit beginnt. Sie können sich selbst an den Prozess des Lesens des Dokuments erinnern. Wenn ich mich selbst als Beispiel nehme, schaue ich mir normalerweise zuerst das Verzeichnis an und suche dann nach den gewünschten Teilen, und ich werde nie das gesamte Dokument von Anfang bis Ende lesen.
Wie lassen Sie andere wissen, dass Sie ein Dokument zu diesem Thema verfasst haben?
Nehmen Sie als Beispiel meine jüngste Erfahrung.
Ich war in den letzten Monaten für das Produktmanagementsystem des Unternehmens verantwortlich. Um Benutzer (andere F&E-Kollegen des Unternehmens) zu fördern und mit diesem System vertraut zu machen, habe ich viele Dokumente geschrieben, von der Grundkonfiguration bis zur Berechtigungsverwaltung. zu Best Practices, aber immer noch oft Wenn jemand kommt, um Fragen zu stellen, zu denen bereits Dokumente vorliegen.
Wir haben ein wenig optimiert und es fühlt sich ein wenig nützlich an. Die Optimierungselemente sind wie folgt:
- Erstellen Sie einen Index für das Dokument. Erstellen Sie
ein neues leeres Dokument, fügen Sie alle Links zu anderen Dokumenten in dieses Dokument ein und schreiben Sie eine Beschreibung für jeden Link. Teilen Sie den Lesern mit, welches Problem in diesem Link aufgezeichnet ist und dass diese Beschreibung korrekt ist. Behalten Sie es als möglichst kurz.
Dies hat den Vorteil, dass Leser nicht zwischen verschiedenen Seiten wechseln müssen, um ein fragliches Dokument zu finden, was die Schwierigkeit verringert, Dokumente zu finden (nicht anzusehen). - Erstellen Sie ein Kundendienstsystem.
Unser Unternehmen verfügt über ein Dialogsystem, das anhand von Schlüsselwörtern auf der Grundlage von Benutzereingaben Links zu entsprechenden Dokumenten zurückgeben kann. Ich habe dem Dokument einige Tags (Schlüsselwörter) hinzugefügt, damit das System das entsprechende Dokument zurückgeben kann, wenn der Benutzer eine Frage stellt. Dieses Dialogsystem ist jedoch etwas albern und der Effekt ist nicht sehr gut (aber nützlich). Daher hängt die aktuelle Arbeit in diesem Bereich hauptsächlich von der Hilfe eines anderen Kollegen ab, der den entsprechenden Link entsprechend der Frage des Benutzers bereitstellt . Aber chatGPT hat mir gezeigt, dass diese Methode in Zukunft definitiv effektiver sein wird. Wenn chatGPT die Unternehmensversion veröffentlicht, können wir sie anhand unserer eigenen Dokumente und FAQ trainieren und dann chatGPT die Fragen der Benutzer beantworten lassen. - Bewerben Sie neu erstellte Dokumente und Dokumente mit mehr Besuchen von Zeit zu Zeit.
Wir werden unsere neu erstellten Dokumente und Dokumente mit mehr Besuchen von Zeit zu Zeit an Benutzer (Gruppen und E-Mails) senden. Aber Sie müssen die Häufigkeit im Auge behalten. Wenn sie zu häufig vorkommt, werden sich die Benutzer ekeln und es wird kontraproduktiv sein.
Ist Ihr Dokument für Leser verständlich?
Einer der einfachsten Fehler beim Schreiben von Dokumentationen (einschließlich Bloggen) besteht darin, nicht aus der Sicht des Lesers zu schreiben.
Wir neigen dazu, auf der Grundlage unseres eigenen Wissens und unserer Erfahrung zu schreiben, was jedoch oft dazu führt, dass die Leser die von uns verfassten Dokumente nicht verstehen können.
Eine der einfachsten Möglichkeiten zur Überprüfung besteht darin, zwei bis drei andere Kollegen um Hilfe bei der Durchsicht des Dokuments zu bitten, um festzustellen, ob sie es verstehen.
Es gibt eine Methode im Schreibprozess, die dieses Problem bis zu einem gewissen Grad lösen kann. Das heißt, beim Schreiben jedes Dokuments müssen Leser ohne Erfahrung berücksichtigt werden und die im aktuellen Dokument benötigten Vorwissenspunkte und Dokumente werden verknüpft. Das Formular wird im Dokument platziert, sodass Leser es bei Bedarf anzeigen können. Tatsächlich tun dies viele hervorragende Open-Source-Softwaredokumente.
Wie werden diese Dokumente gepflegt?
Mit der Zeit schreiben wir immer mehr Dokumente, von denen einige möglicherweise veraltet sind. Wie sollen wir also damit umgehen?
Manchmal sind unordentliche und veraltete Dokumente schädlich für die Arbeit. Wenn beispielsweise die Änderung der Funktion des Systemparameters nicht rechtzeitig aktualisiert wird und der Benutzer einen destruktiven Parameter verwendet, kann dies schwerwiegende Folgen haben.
Ich unterteile die Wartung in zwei Teile: Verwaltung und Aktualisierung.
verwalten
Unser Unternehmen hat das Atlassian-Wiki zum Schreiben von Dokumenten verwendet. Im Allgemeinen ist dies recht gut. Dokumente können entsprechend der Organisationsstruktur und dem Produktkatalog angeordnet werden. Es wird gesagt, dass Feishu auch ähnliche Funktionen erreichen kann.
Kürzlich hat ein kleiner Partner im Team eine neue Methode zur Dokumentenverwaltung entdeckt. Ich finde sie sehr gut und habe vor, sie auszuprobieren.
Legen Sie das Dokument in Form einer Markdown-Datei im Repository von Github (unserem firmeneigenen Github) ab und synchronisieren Sie es dann über ein Plug-In mit dem Wiki. Dies hat den offensichtlichen Vorteil einer Versionsverwaltungsfunktion, da das Wiki von Atlassian selbst Es gibt keine solche Funktion. Darüber hinaus können Sie Dokumente über Markdown schreiben, was für Programmierer benutzerfreundlicher ist.
erneuern
Eine weitere große Herausforderung bei der Pflege der Dokumentation ist die Aktualisierung, insbesondere der unternehmensintern freigegebenen Softwaredokumentation.
Denn wenn es sich um kommerzielle Software handelt, muss die Dokumentation aktualisiert werden. Dies wird sowohl durch den Druck kommerzieller Kunden (Vater von Partei A) als auch durch den Gewinn auf dem Markt (Geldverdienen ￥￥) vorangetrieben, sodass es oft nicht notwendig ist, kommerziell zu bleiben Software aktualisiert. Eine zu große Frage.
Bei der vom Unternehmen intern veröffentlichten Software ist es jedoch aufgrund des Fehlens der beiden oben genannten treibenden Faktoren etwas schwierig, die Dokumentation auf dem neuesten Stand zu halten.
Es gibt jedoch zwei Möglichkeiten, die Dokumentation möglichst aktuell zu halten .
- Wählen Sie diejenigen im Team aus, die perfekter sind und für die interne Software verantwortlich sind.
Solche Leute ergreifen aufgrund ihres Strebens nach Perfektion oft die Initiative, Dokumente zu aktualisieren - Richten Sie einen Dokumentenprüfungsmechanismus ein
. Zumindest für diese sehr wichtigen Systeme sollte ein Dokumentenprüfungsmechanismus eingerichtet werden.
Dies hat zwei Vorteile: Der eine besteht darin, die Dokumente so auf dem neuesten Stand zu halten, wie sie sein sollten, und der andere darin, andere Personen im Team mit diesen Dokumenten vertraut zu machen, da sie an der Überprüfung teilnehmen müssen, wodurch ein gewisses Maß an Kommunikation zwischen ihnen erreicht werden kann Teammitglieder. Backup.
Ist die von Ihnen verfasste Dokumentation notwendig?
Als ich zum ersten Mal für das Produktmanagementsystem verantwortlich war, habe ich viel Zeit damit verbracht, Dokumente zu schreiben, in der Hoffnung, so umfassend wie möglich zu sein. Später stellte ich jedoch fest, dass einige der Dokumente unnötig waren.
Woher wissen Sie also, ob das von Ihnen verfasste Dokument notwendig ist?
Es gibt zwei Methoden, die vor und nach dem Schreiben des Dokuments verwendet werden.
Nachdem Sie das Dokument geschrieben haben, können Sie auf den Leseumfang des Dokuments achten. Wenn es noch niemand gelesen hat oder der Leseumfang sehr gering ist, bedeutet dies, dass das Dokument möglicherweise nicht erforderlich ist. (oder sehr schlecht geschriebene Dokumentation)
Bevor Sie ein Dokument schreiben, können Sie Benutzerfragen sammeln, bevor Sie mit dem Schreiben beginnen, um nicht mit dem Schreiben eines Dokuments nach Ihren eigenen Vorlieben zu beginnen.