Manchmal kann nicht nur die Dokumentation selbst, sondern auch der Prozess der Bearbeitung kritisch sein. Beispielsweise ist bei Projekten der Löwenteil der Arbeit mit der Erstellung von Dokumentationen verbunden, und ein falscher Prozess kann zu Fehlern und sogar zum Verlust von Informationen und folglich zu Zeit- und Gewinnverlust führen. Aber auch wenn dieses Thema für Ihre Arbeit nicht von zentraler Bedeutung ist und sich an der Peripherie befindet, kann der richtige Prozess die Qualität des Dokuments verbessern und Ihnen Zeit sparen.
Der hier skizzierte Ansatz mit
einem Beispiel für eine bestimmte Implementierung weist eine niedrige Eintrittsschwelle auf. Technisch gesehen können Sie morgen auf eine neue Art und Weise arbeiten.
Erklärung des Problems
Sie müssen ein bestimmtes Dokument oder eine Reihe von Dokumenten erstellen. Vielleicht ist dies eine Projektdokumentation oder Protokollierung Ihres Netzwerks oder etwas Einfacheres. Sie sollten beispielsweise die Prozesse im Unternehmen oder in Ihrer Abteilung beschreiben. Im Allgemeinen sprechen wir über jedes Dokument oder jede Reihe von Dokumenten mit Text, Bildern, Tafeln ... Wir erschweren die Aufgabe dadurch, dass
- Diese Arbeit beinhaltet gemeinsame Arbeit, die Bemühungen einer Gruppe oder mehrerer Gruppen von Mitarbeitern
- Bei der Ausgabe möchten Sie ein Dokument in einem bestimmten Format mit Attributen im Unternehmensstil haben, das nach einer bestimmten Vorlage erstellt wird. Für die Bestimmtheit nehmen wir an, dass dies MS Word (.docx) ist.
Vor 10 Jahren war der Ansatz eindeutig: Wir würden ein oder mehrere MS Word-Dokumente erstellen und die Arbeit an der Änderung irgendwie organisieren.
Und dieser Ansatz ist immer noch gültig. Es wird auch von großen Integratoren beim Erstellen von Projektdokumentationen verwendet. Es ist jedoch intuitiv klar, dass dieser Ansatz nicht sehr praktisch ist, wenn Sie mit vielen Änderungen und Diskussionen sehr intensiv an einer langen Zeit an einem Dokument arbeiten.
Beispiel
Ich habe dieses Problem sehr akut gespürt, als ich in einem großen Integrator gearbeitet habe. Der Prozess zum Ändern der Konstruktionsdokumentation war wie folgt:
- Der Ingenieur lädt die neueste Version des MS Word-Dokuments (.docx) herunter
- ändert den Namen
- nimmt Änderungen am Track Mod vor
- sendet das Dokument mit Korrekturen an den Architekten
- sendet auch eine Liste aller Korrekturen mit Kommentaren
- Architekt analysiert Veränderung
- Wenn alles in Ordnung ist, werden die Änderungsdaten mit der neuesten Version in die Datei kopiert, die Version geändert und in eine gemeinsam genutzte Ressource gestellt
- Wenn es Kommentare gibt, wird eine Diskussion eingeleitet (E-Mail oder Kundgebungen).
- Konsens ist erreicht
- weitere Absätze 3 - 9
Die Arbeit war zwar nicht intensiv, aber irgendwie funktionierte sie trotzdem. Ab einem bestimmten Punkt wurde dieser Prozess jedoch zum Engpass des gesamten Projekts und führte zu Problemen. Tatsache ist, dass alles schlecht wird, sobald Änderungen häufig und gleichzeitig von mehreren Teams vorgenommen werden.
Als wir zur vorläufigen Testphase gingen, traten verschiedene Probleme auf, und obwohl wir im Detail waren, mussten wir die Dokumentation häufig ändern - vier verschiedene Teams, täglich, fast gleichzeitig, mit Diskussionen. Alle diese Änderungen wurden von einem Ingenieur durchgeführt - einem Architekten. Die Datei mit dem Design des Projekts war riesig, und infolgedessen war der Architekt von der Routinearbeit überwältigt, die mit viel Kopieren, Bearbeiten, vielen Fehlern verbunden war. Ich musste sie überprüfen, erneut senden und im Allgemeinen war sie dem Chaos nahe.
In diesem Fall arbeitete dieser Ansatz, der Ansatz, an einem MS Word-Dokument zu arbeiten, mit großem Quietschen und verursachte Probleme.
Git Markdown
Angesichts des im obigen Beispiel beschriebenen Problems begann ich, dieses Problem zu untersuchen.
Ich habe gesehen, dass die Verwendung von
Markdown mit
Git beim Erstellen von Dokumenten immer beliebter wird.
Git ist ein Entwicklungswerkzeug. Aber warum nicht für den Dokumentationsprozess verwenden? In diesem Fall wird das Problem der Mehrbenutzerarbeit behoben. Um die Git-Funktionen voll nutzen zu können, benötigen wir ein Textformat für das Dokument. Wir müssen ein anderes Tool finden, nicht MS Word, und Markdown eignet sich hervorragend für diese Zwecke.
Markdown ist eine einfache Text-Markup-Sprache. Es wurde entwickelt, um wunderschön gestaltete Texte in regulären TXT-Dateien zu erstellen. Wenn wir unsere Dokumente in Markdown erstellen, sieht der Markdown-Git-Link natürlich aus.
Und alles wäre in Ordnung, und an dieser Stelle wäre es möglich, ein Ende zu setzen, wenn es nicht unsere zweite Bedingung gäbe: „Bei der Ausgabe benötigen wir ein Dokument in einem bestimmten Format mit Attributen im Unternehmensstil, das nach einer bestimmten Vorlage erstellt wurde“ (und wir haben uns zunächst darauf geeinigt) Gewissheit, es wird MS Word sein). Das heißt, wenn wir uns für Markdown entschieden haben, müssen wir diese Datei irgendwie in .docx des erforderlichen Typs konvertieren.
Es gibt Programme zum Konvertieren zwischen verschiedenen Formaten, zum Beispiel
Pandoc .
Mit diesem Programm können Sie die Markdown-Datei in das DOCX-Format konvertieren.
Dennoch müssen Sie verstehen, dass erstens nicht alles, was in Markdown enthalten ist, in MS Word konvertiert wird, und zweitens ist MS Word im Vergleich zu der schlanken, aber immer noch kleinen Stadt Markdown ein ganzes Land. Es gibt eine große Menge von allem, was in Word und in keiner Form in Markdown enthalten ist. Sie können Ihr Markdown-Format nicht einfach mit den gewünschten Pandoc-Schlüsseln in die gewünschte Form von MS Word übernehmen. Daher müssen Sie das empfangene DOCX-Dokument nach der Konvertierung normalerweise manuell „verfeinern“, was wiederum zeitaufwändig sein und zu Fehlern führen kann.
Wenn wir ein Skript schreiben könnten, das automatisch „beendet“, was Pandoc nicht kann, wäre dies eine ideale Lösung.
Aufgrund der Tatsache, dass die Funktionen von MS Word und Markdown im Allgemeinen nicht identisch sind, ist es meines Erachtens unmöglich, dieses Problem zu lösen. Kann dies jedoch in Bezug auf bestimmte Situationen und bestimmte Anforderungen erfolgen? Meine Erfahrung hat gezeigt, dass dies möglich und höchstwahrscheinlich für viele oder sogar für die meisten Situationen möglich ist.
Lösung eines bestimmten Problems
In meinem Fall musste ich nach dem Konvertieren der Datei mit Pandoc manuell eine zusätzliche Dateiverarbeitung durchführen, nämlich
- Fügen Sie Felder in Word mit automatischer Nummerierung der Beschriftungen von Tabellen und Bildern hinzu
- Ändern Sie den Stil für Tabellen
Ich habe nicht herausgefunden, wie dies mit Standard (Pandoc) oder bekannten Mitteln gemacht werden kann. Daher habe ich mit dem
pywin32- Paket ein Python-Skript
angewendet . Als Ergebnis bekam ich volle Automatisierung. Jetzt kann ich meine Markdown-Datei mit einem Befehl in die gewünschte Form eines MS Word-Dokuments konvertieren.
Details finden Sie
hier .
Bemerkung
In diesem Beispiel werde ich natürlich eine abstrakte Markdown-Datei konvertieren, aber genau der gleiche Ansatz wurde auf das "Kampf" -Dokument angewendet, und bei der Ausgabe erhielt ich fast genau das gleiche MS Word-Dokument, das wir zuvor durch manuelle Formatierung erhalten hatten.
Im Allgemeinen erhalten wir mit pywin32 fast die vollständige Kontrolle über das MS Word-Dokument, sodass wir es ändern und an das Aussehen anpassen können, das Ihr Unternehmensstandard erfordert. Natürlich könnten die gleichen Ziele mit anderen Tools erreicht werden, zum Beispiel mit VBA-Makros, aber es war für mich bequemer, Python zu verwenden.
Eine kurze Formel für diesen Ansatz:
Markdown + Git -- () --> MS Word
Nicht so wichtig, was "etwas" ist. In meinem Fall war es Pandoc und Python mit pywin32. Möglicherweise haben Sie unterschiedliche Einstellungen, aber das Wichtigste ist, dass dies möglich ist. Und das ist die Hauptbotschaft dieses Artikels.
Zusammenfassend lässt sich sagen, dass Sie bei diesem Ansatz nur mit der Markdown-Datei arbeiten und Git verwenden, um die Zusammenarbeit und Versionskontrolle zu organisieren, und nur bei Bedarf (z. B. um dem Client Dokumentation bereitzustellen) automatisch die Datei des gewünschten Formats (z. B. MS Word) erstellen )
Der Prozess
Ich denke, für viele reicht die oben angegebene Formel aus, um zu verstehen, wie der Prozess der Arbeit mit der Dokumentation jetzt organisiert werden kann. Trotzdem konzentriere ich mich normalerweise auf Netzwerktechniker. Daher werde ich allgemein skizzieren, wie der Prozess jetzt aussehen kann und wie er sich vom Ansatz zum Bearbeiten von MS Word-Dateien unterscheidet.
Aus Bestimmtheit wählen wir GitHub als Plattform für die Arbeit mit Git. Anschließend müssen Sie ein Repository erstellen und die Markdown-Datei oder Dateien, mit denen Sie arbeiten möchten, in den Hauptzweig einfügen.
Wir werden uns einen einfachen Github-Flow-basierten Prozess ansehen. Die Beschreibung finden Sie sowohl im Internet als auch im
Habr .
Angenommen, vier Personen arbeiten an der Dokumentation und Sie sind einer von ihnen. Anschließend werden beispielsweise vier zusätzliche Zweige mit den Namen dieser Personen erstellt. Jeder arbeitet lokal in einem eigenen Zweig und nimmt Änderungen mit allen erforderlichen
Git-Befehlen vor .
Nachdem Sie einige abgeschlossene Arbeiten abgeschlossen haben, bilden Sie eine Pull-Anfrage und initiieren so eine Diskussion Ihrer Änderungen. Vielleicht stellt sich im Diskussionsprozess heraus, dass Sie etwas anderes hinzufügen oder ändern sollten. In diesem Fall nehmen Sie die erforderlichen Änderungen vor und erstellen eine zusätzliche Pull-Anforderung. Am Ende werden Ihre Änderungen akzeptiert und mit dem Hauptzweig zusammengeführt (oder abgelehnt).
Dies ist natürlich eine ziemlich allgemeine Beschreibung. Ich schlage vor, Ihre Entwickler zu kontaktieren oder sachkundige Personen zu finden, um einen detaillierten Prozess zu erstellen. Ich möchte jedoch darauf hinweisen, dass der Schwellenwert für die Eingabe von Git ziemlich niedrig ist. Dies bedeutet nicht, dass das Protokoll einfach ist, aber Sie können mit einem einfachen beginnen. Wenn Sie überhaupt nichts wissen, können Sie, nachdem Sie mehrere Stunden oder vielleicht Tage mit Lernen und Installieren verbracht haben, damit beginnen.
Was nützt dieser Ansatz beispielsweise im Vergleich zu dem im obigen Beispiel beschriebenen Prozess?
In der Tat sind die Prozesse ziemlich ähnlich, Sie haben gerade ersetzt
Kopieren einer Datei -> Erstellen eines Zweigs
Text in endgültige Datei kopieren-> zusammenführen (zusammenführen)
Kopieren Sie die neuesten Änderungen in sich selbst -> Git Pull / Fetch
Korrespondenzdiskussion -> Anfragen ziehen
Track-Modus -> Git-Diff
letzte genehmigte Version -> Hauptzweig
Backup (Kopieren auf einen Remote-Server) -> Git Push
...
So haben Sie alles automatisiert, was Sie bereits tun mussten, aber manuell.
Auf einer höheren Ebene ermöglicht dies Ihnen
- Erstellen Sie einen klaren, einfachen und kontrollierten Prozess zum Ändern der Dokumentation.
- weil Wenn Sie das endgültige Dokument (in unserem Beispiel MS Word) automatisch erstellen, verringert sich die Wahrscheinlichkeit von Fehlern bei der Formatierung
Bemerkung
In Anbetracht des oben Gesagten denke ich, dass es offensichtlich ist, dass die Verwendung von Git Ihre Arbeit erheblich erleichtern kann, selbst wenn Sie nur an der Dokumentation arbeiten
All dies verbessert die Qualität der Dokumentation und verkürzt die Zeit für deren Erstellung. Und ein kleiner Bonus - du lernst Git, was dir bei der Automatisierung deines Netzwerks hilft :)
Wie wechsle ich zu einem neuen Prozess?
Am Anfang des Artikels habe ich geschrieben, dass Sie morgen auf eine neue Art und Weise arbeiten können. Wie können Sie Ihre Arbeit in eine neue Richtung übersetzen?
Hier ist die Abfolge der Schritte, die Sie höchstwahrscheinlich ausführen müssen:
- Wenn Ihr Dokument sehr groß ist, brechen Sie es in Stücke
- Konvertieren Sie jedes Teil in Markdown (z. B. mit Pandoc).
- Installieren Sie einen der Markdown-Editoren (ich verwende Typora ).
- Höchstwahrscheinlich müssen Sie die Formatierung der erstellten Markdown-Dokumente anpassen
- Beginnen Sie mit der Anwendung des im vorherigen Kapitel beschriebenen Prozesses
- Beginnen Sie parallel damit, das Konvertierungsskript an Ihre Aufgabe anzupassen (oder erstellen Sie etwas Eigenes).
Sie müssen nicht warten, bis Sie den für den Ausgabedokumenttyp erforderlichen Markdwon -> Konvertierungsmechanismus erstellt und perfekt debuggt haben. Tatsache ist, dass Sie die Konvertierung Ihrer Markdown-Dateien auch dann, wenn Sie die Konvertierung Ihrer Markdown-Dateien nicht schnell und vollständig automatisieren können, mit Pandoc in beliebiger Form ausführen und dann manuell in die endgültige Form bringen können. Normalerweise müssen Sie dies nicht oft tun, sondern erst am Ende bestimmter Phasen, und diese manuelle Arbeit ist, obwohl sie unpraktisch ist, meiner Meinung nach in der Debugging-Phase immer noch akzeptabel und sollte den Prozess nicht wesentlich verlangsamen.
Alles andere (Markdown, Git, Pandoc, Typora) ist fertig und erfordert keine besonderen Anstrengungen oder Zeit, um mit ihnen zu arbeiten.