Verwenden Sie GIT zum Dokumentieren

Manchmal kann nicht nur die Dokumentation selbst, sondern auch der Prozess der Bearbeitung entscheidend sein. Beispielsweise entfällt bei Projekten der Löwenanteil der Arbeit auf die Erstellung der Dokumentation, und ein falscher Prozess kann zu Fehlern und sogar Informationsverlusten und damit zu Zeit- und Nutzenverlusten führen. Aber auch wenn dieses Thema nicht im Mittelpunkt Ihrer Arbeit steht und nur am Rande liegt, kann der richtige Prozess dennoch die Qualität des Dokuments verbessern und Ihnen Zeit sparen.

Der hier skizzierte Ansatz mit Beispiel einer konkreten Implementierung, hat eine niedrige Eintrittsbarriere. Technisch gesehen können Sie morgen auf eine neue Art und Weise mit der Arbeit beginnen.

Formulierung des Problems

Sie müssen ein Dokument oder eine Reihe von Dokumenten erstellen. Vielleicht handelt es sich dabei um eine Projektdokumentation oder Protokollierung Ihres Netzwerks, oder auch um etwas Einfacheres, Sie müssen beispielsweise die Prozesse im Unternehmen oder in Ihrer Abteilung beschreiben. Im Allgemeinen handelt es sich um jedes Dokument oder jede Dokumentengruppe mit Text, Bildern, Zeichen ... Erschweren wir die Aufgabe dadurch

1. Bei dieser Arbeit handelt es sich um gemeinsame Arbeit, die Anstrengungen einer Gruppe oder mehrerer Gruppen von Mitarbeitern
2. Daher möchten Sie ein Dokument in einem bestimmten Format mit Corporate-Style-Attributen haben, das nach einer bestimmten Vorlage erstellt wird. Konkret gehen wir davon aus, dass es sich um MS Word (.docx) handelt.

Vor 10 Jahren wäre der Ansatz noch unkompliziert gewesen: Wir hätten ein oder mehrere MS Word-Dokumente erstellt und die Änderungsarbeiten irgendwie organisiert.

Und dieser Ansatz ist immer noch gültig. Es wird auch von großen Integratoren bei der Erstellung von Projektdokumentationen verwendet. Aber es ist intuitiv klar, dass dieser Ansatz nicht sehr praktisch ist, wenn man wirklich intensiv und über einen längeren Zeitraum an einem Dokument mit vielen Bearbeitungen und Diskussionen arbeitet.

Beispiel

Ich habe dieses Problem sehr deutlich gespürt, als ich für einen großen Integrator gearbeitet habe. Der Prozess zur Änderung der Designdokumentation war wie folgt:

1. Der Ingenieur lädt die neueste Version des MS Word-Dokuments (.docx) herunter
2. ändert den Namen
3. nimmt Änderungen vor, um die Mode zu verfolgen
4. sendet das Dokument mit Änderungen an den Architekten
5. sendet außerdem eine Liste aller Korrekturen mit Kommentaren
6. Architekt analysiert Veränderungen
7. Wenn alles in Ordnung ist, kopiert es diese Änderungen in eine Datei mit der neuesten Version, ändert die Version und lädt sie auf eine gemeinsam genutzte Ressource hoch
8. bei Kommentaren wird eine Diskussion eingeleitet (E-Mail oder Meetings)
9. Konsens erreicht wird
10. weitere Punkte 3 - 9

Die Arbeit war zwar nicht intensiv, aber irgendwie, aber es hat trotzdem funktioniert. Doch ab einem bestimmten Punkt wurde dieser Prozess zum Flaschenhals des gesamten Projekts und führte zu Problemen. Der Punkt ist, dass es schlecht wird, sobald von mehreren Teams häufig und gleichzeitig Änderungen vorgenommen werden.

Als wir also in die vorläufige Testphase übergingen, traten verschiedene Probleme auf und, wenn auch in kleinen Mengen, war es notwendig, die Dokumentation häufig zu ändern – vier verschiedene Teams, jeden Tag, fast gleichzeitig, mit Diskussionen. Alle diese Änderungen wurden von einem Ingenieur durchgeführt – einem Architekten. Die Projektentwurfsdatei war riesig, und infolgedessen war der Architekt mit Routinearbeiten überfordert, die viel Kopieren und Bearbeiten erforderten, er machte viele Fehler, musste alles noch einmal überprüfen, es erneut senden, und im Allgemeinen war es nah dran Chaos.

In diesem Fall funktionierte dieser Ansatz, die Arbeit an einem MS-Word-Dokument, nur mit großen Schwierigkeiten 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.

Git ist ein Entwicklungstool. Aber warum nicht für den Dokumentationsprozess nutzen? In diesem Fall wird das Problem der Mehrbenutzerarbeit gelöst. Um die Fähigkeiten von Git jedoch voll ausnutzen zu können, benötigen wir ein Textdokumentformat, wir müssen ein anderes Tool als MS Word finden, und Markdown eignet sich hervorragend für diese Zwecke.

Markdown ist eine einfache Textauszeichnungssprache. Es wurde entwickelt, um schön gestaltete Texte in regulären TXT-Dateien zu erstellen. Wenn wir unsere Dokumente in Markdown erstellen, sieht die Markdown-Git-Kombination natürlich aus.

Und alles wäre gut, und an diesem Punkt könnten wir damit Schluss machen, wenn nicht unsere zweite Bedingung wäre: „Als Ergebnis benötigen wir ein Dokument in einem bestimmten Format, mit den Attributen eines Unternehmensstils, erstellt nach.“ eine bestimmte Vorlage“ (und wir waren uns zu Beginn einig, dass es sicherlich MS Word sein wird). Das heißt, wenn wir uns für die Verwendung von Markdown entscheiden, müssen wir diese Datei irgendwie in eine .docx-Datei des erforderlichen Typs konvertieren.

Es gibt Programme zum Konvertieren zwischen verschiedenen Formaten, z.B. Pandak.
Mit diesem Programm können Sie Markdown-Dateien 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 MS Word im Vergleich zu der schlanken, aber immer noch kleinen Stadt Markdown ein ganzes Land ist. Es gibt eine große Menge von allem, was in Word enthalten ist, das in Markdown in keiner Form vorliegt. Sie können Ihr Markdown-Format nicht einfach mit bestimmten Pandoc-Schlüsseln in das gewünschte MS Word-Format konvertieren. Normalerweise müssen Sie nach der Konvertierung das resultierende .docx-Dokument manuell „bearbeiten“, was wiederum zeitaufwändig sein und zu Fehlern führen kann.

Wenn wir ein Skript schreiben könnten, das automatisch „fertigstellt“, was Pandoc nicht bewältigen konnte, wäre das eine ideale Lösung.

Aufgrund der Nichtidentität der Funktionalität von MS Word und Markdown ist es meiner Meinung nach unmöglich, dieses Problem generell zu lösen, aber kann dies in Bezug auf bestimmte Situationen, bestimmte Anforderungen durchgeführt werden? Meine Erfahrung hat gezeigt, dass es ja möglich ist und höchstwahrscheinlich in vielen, vielleicht sogar den meisten Situationen möglich ist.

Lösung eines bestimmten Problems

In meinem Fall musste ich also nach der Konvertierung der Datei mit Pandoc eine zusätzliche Dateiverarbeitung manuell durchführen, nämlich

• Fügen Sie Felder zu Word mit automatischer Nummerierung der Überschriften (Beschriftungen) von Tabellen und Bildern hinzu
• Tabellenstil ändern

Ich habe nicht herausgefunden, wie man das mit Standard- (Pandoc) oder bekannten Mitteln machen kann. Also habe ich das Python-Skript mit angewendet pywin32 Paket. Dadurch erhielt ich eine vollständige Automatisierung. Jetzt kann ich meine Markdown-Datei mit einem Befehl in die gewünschte MS Word-Dokumentform konvertieren.

Siehe Einzelheiten hier.

Hinweis:

In diesem Beispiel konvertiere ich natürlich eine abstrakte Markdown-Datei, aber genau der gleiche Ansatz wurde auf das „Kampf“-Dokument angewendet, und die Ausgabe, die ich erhielt, war fast genau dasselbe MS Word-Dokument, das wir zuvor durch manuelle Formatierung erhalten hatten .

Im Allgemeinen erhalten wir mit pywin32 eine nahezu vollständige Kontrolle über das MS Word-Dokument, wodurch wir es ändern und in die Form bringen können, die Ihr Unternehmensstandards erfordert. Natürlich könnten die gleichen Ziele auch 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

Es spielt keine Rolle, was „etwas“ ist. In meinem Fall waren es Pandoc und Python mit pywin32. Ihre Vorlieben mögen unterschiedlich sein, aber das Wichtigste ist, dass es möglich ist. Und das ist die Hauptbotschaft dieses Artikels.

Zusammenfassend besteht die Idee darin, dass Sie bei diesem Ansatz nur mit der Markdown-Datei arbeiten und Git für die Zusammenarbeit und Versionskontrolle verwenden und nur bei Bedarf (z. B. um dem Kunden Dokumentation bereitzustellen) automatisch eine Datei im gewünschten Format erstellen ( zum Beispiel MS Word).

Prozess

Ich denke, dass die oben angegebene Formel für viele ausreicht, um zu verstehen, wie der Prozess der Arbeit mit Dokumentation jetzt organisiert werden kann. Dennoch konzentriere ich mich normalerweise auf Netzwerktechniker, daher werde ich allgemein zeigen, wie der Arbeitsprozess jetzt aussehen kann und wie sich dieser von der Vorgehensweise beim Bearbeiten von MS Word-Dateien unterscheidet.

Konkret wählen wir GitHub als Plattform für die Arbeit mit Git. Anschließend sollten Sie ein Repository erstellen und die Markdown-Datei(en), mit denen Sie arbeiten möchten, im Hauptzweig platzieren.

Wir werden uns einen einfachen Prozess ansehen, der auf dem „Github-Flow“ basiert. Die Beschreibung finden Sie sowohl im Internet als auch auf habe.

Nehmen wir an, es arbeiten vier Personen an der Dokumentation und Sie sind einer von ihnen. Dann werden beispielsweise vier weitere Zweige mit den Namen dieser Personen erstellt. Jeder arbeitet vor Ort, in seiner eigenen Filiale und nimmt bei allen notwendigen Änderungen Änderungen vor Git-Befehle.

Nachdem Sie eine abgeschlossene Arbeit abgeschlossen haben, erstellen Sie einen Pull-Request und leiten so eine Diskussion Ihrer Änderungen ein. Vielleicht stellt sich im Laufe der Diskussion heraus, dass Sie noch etwas hinzufügen oder ändern sollten. In diesem Fall nehmen Sie die notwendigen Änderungen vor und erstellen einen zusätzlichen Pull-Request. Schließlich werden Ihre Änderungen akzeptiert und im Hauptzweig zusammengeführt (oder verworfen).

Natürlich ist dies eine ziemlich allgemeine Beschreibung. Um einen detaillierten Prozess zu erstellen, empfehle ich Ihnen, sich an Ihre Entwickler zu wenden oder sachkundige Personen zu finden. Ich möchte jedoch darauf hinweisen, dass die Hürde für den Einstieg in Git recht niedrig ist. Das soll nicht heißen, dass das Protokoll einfach ist, aber Sie können einfach anfangen. Wenn Sie überhaupt nichts wissen, können Sie meiner Meinung nach nach ein paar Stunden oder vielleicht Tagen mit dem Lernen und Installieren damit beginnen.

Welchen Vorteil hat dieser Ansatz beispielsweise im Vergleich zu dem im obigen Beispiel beschriebenen Verfahren?

Tatsächlich sind die Prozesse ziemlich ähnlich, Sie haben sie nur ersetzt

Kopieren einer Datei -> Erstellen eines Zweigs
Text in die endgültige Datei kopieren -> zusammenführen
Kopieren Sie die neuesten Änderungen auf sich selbst -> Git Pull/Fetch
Diskussion in der Korrespondenz -> Pull Requests
Track-Modus -> Git Diff
letzte genehmigte Version -> Hauptzweig
Backup (Kopieren auf einen Remote-Server) -> Git Push
...

Somit haben Sie alles automatisiert, was Sie bereits tun mussten, allerdings manuell.

Auf einer höheren Ebene ermöglicht es Ihnen

• Erstellen Sie einen klaren, einfachen und kontrollierten Prozess für Dokumentänderungen
• Weil Da Sie das endgültige Dokument (in unserem Beispiel MS Word) automatisch erstellen, verringert sich die Wahrscheinlichkeit von Formatierungsfehlern

Hinweis:

Dennoch denke ich, dass es offensichtlich ist, dass die Verwendung von Git Ihre Arbeit erheblich erleichtern kann, auch 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 noch ein kleiner Bonus: Sie lernen Git, was Ihnen bei der Automatisierung Ihres Netzwerks hilft :)

Wie wechselt man zu einem neuen Prozess?

Am Anfang des Artikels habe ich geschrieben, dass Sie morgen auf neue Weise mit der Arbeit beginnen können. Wie können Sie Ihrer Arbeit eine neue Richtung geben?

Hier ist die Reihenfolge der Schritte, die Sie höchstwahrscheinlich befolgen müssen:

• Wenn Ihr Dokument sehr groß ist, teilen Sie es in Teile auf
• Konvertieren Sie jeden 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 gleichzeitig damit, das Konvertierungsskript an Ihre Aufgabe anzupassen (oder erstellen Sie etwas Eigenes).

Sie müssen nicht warten, bis Sie den Markdwon-Konvertierungsmechanismus erstellt und perfektioniert haben -> den erforderlichen Ausgabetyp des Dokuments. Der Punkt ist, dass Sie die Konvertierung Ihrer Markdown-Dateien auch dann nicht schnell und vollständig automatisieren können, dass Sie sie dennoch in irgendeiner Form mit Pandoc durchführen und sie dann manuell in die endgültige Form bringen können. Normalerweise müssen Sie dies nicht oft tun, sondern nur am Ende bestimmter Phasen. Diese manuelle Arbeit ist zwar unbequem, aber meiner Meinung nach in der Debugging-Phase durchaus akzeptabel und sollte den Prozess nicht „verlangsamen“. viel.

Alles andere (Markdown, Git, Pandoc, Typora) ist bereits fertig und erfordert weder viel Aufwand noch Zeit, um damit zu arbeiten.

Source: habr.com