Verwenden Sie GIT bei der Dokumentation

Manchmal kann nicht nur die Dokumentation selbst, sondern auch der Prozess zu ihrer Erstellung kritisch sein. Zum Beispiel ist ein großer Teil der Arbeit in Projekten tatsächlich mit der Erstellung von Dokumentationen verbunden, und ein falscher Prozess kann zu Fehlern und sogar zu Informationsverlust führen, was wiederum Zeit und Nutzen kostet. Aber selbst wenn dieses Thema nicht zentral in Ihrer Arbeit ist und sich am Rande befindet, kann ein korrekter Prozess trotzdem die Qualität des Dokuments verbessern und Ihnen Zeit sparen.

Der hier dargestellte Ansatz, mit einem Beispiel für eine konkrete Umsetzung, hat eine niedrige Einstiegshürde. Technisch gesehen können Sie bereits morgen anders arbeiten.

Aufgabenstellung

Sie müssen ein Dokument oder eine Dokumentensammlung erstellen. Möglicherweise handelt es sich um Projektdokumentation oder Protokollierung Ihres Netzwerks, oder um etwas Einfacheres, zum Beispiel müssen Sie Prozesse in Ihrem Unternehmen oder Ihrer Abteilung beschreiben. Es geht im Allgemeinen um jedes Dokument oder Dokumentenset mit Texten, Bildern, Tabellen... Wir complicieren die Aufgabe damit, dass

1. diese Arbeit gemeinschaftliche Anstrengungen, die Zusammenarbeit von Gruppen oder mehreren Gruppen von Mitarbeitern erfordert
2. Am Ende möchten Sie ein Dokument in einem bestimmten Format haben, mit Attributen des Corporate Designs, das nach einer bestimmten Vorlage erstellt wurde. Zum Klarstellen gehen wir davon aus, dass dies MS Word (.docx) ist.

Vor 10 Jahren wäre der Ansatz eindeutig gewesen: Wir hätten ein MS Word-Dokument oder mehrere Dokumente erstellt und die Arbeit an den Änderungen irgendwie organisiert.

Und dieser Ansatz ist nach wie vor gültig. Er wird auch von großen Integratoren bei der Erstellung von Projektdokumentationen verwendet. Aber es ist intuitiv klar, dass, wenn Sie wirklich intensiv, mit vielen Änderungen und Diskussionen, über längere Zeit an einem Dokument arbeiten, dieser Ansatz nicht sehr praktisch ist.

Beispiel

Ich habe dieses Problem ziemlich stark gespürt, als ich in einem großen Integrator gearbeitet habe. Der Prozess zur Änderung der Projektdokumentation war folgender:

1. Der Ingenieur lädt die neueste Version des MS Word-Dokuments (.docx) herunter
2. ändert den Titel
3. nimmt Änderungen im Track-Modus vor
4. sendet das Dokument mit den Änderungen an den Architekten
5. sendet auch eine Liste aller Korrekturen mit Kommentaren
6. der Architekt analysiert die Änderungen
7. Wenn alles gut ist, werden die Änderungen der Daten in die Datei mit der neuesten Version kopiert, die Version geändert und auf die gemeinsame Ressource hochgeladen.
8. Wenn es Anmerkungen gibt, wird eine Diskussion initiiert (per E-Mail oder Meetings).
9. Es wird ein Konsens erreicht.
10. Dann die Punkte 3 – 9.

Solange die Arbeit nicht intensiv war, hat es einigermaßen funktioniert, aber es hat trotzdem funktioniert. Doch irgendwann wurde dieser Prozess zum Engpass des gesamten Projekts und führte zu Problemen. Das Problem ist, dass alles schlecht wird, sobald Änderungen häufig und gleichzeitig von mehreren Teams vorgenommen werden.

Als wir in die Phase der Vorprüfung übergingen, traten verschiedene Probleme auf, und obwohl es Kleinigkeiten waren, musste die Dokumentation häufig geändert werden – vier verschiedene Teams täglich, praktisch gleichzeitig, mit Diskussionen. Alle diese Änderungen gingen über einen Ingenieur – den Architekten. Die Entwurfsdatei des Projekts war riesig und in der Folge war der Architekt mit der Routinearbeit, die mit viel Kopieren und Bearbeiten verbunden war, überlastet, machte viele Fehler, musste alles erneut überprüfen und weitersenden, und im Großen und Ganzen war es nahe am Chaos.

In diesem Fall hat dieser Ansatz, mit dem Dokument MS Word zu arbeiten, mit großem Aufwand funktioniert und Probleme geschaffen.

Git, Markdown

Bei der Konfrontation mit dem oben beschriebenen Problem begann ich, diese Frage zu erforschen.
Ich sah, dass die Verwendung von Markdown in Kombination mit Git bei der Erstellung von Dokumenten immer beliebter wird.

Git ist ein Werkzeug für die Entwicklung. Aber warum es nicht für den Dokumentationsprozess nutzen? In diesem Fall wird die Frage der Mehrbenutzerarbeit gelöst. Um jedoch die Möglichkeiten von Git voll auszuschöpfen, benötigen wir ein Textformat für das Dokument, wir müssen ein anderes Werkzeug finden, nicht MS Word, und dafür eignet sich Markdown hervorragend.

Markdown ist eine einfache Markup-Sprache. Sie ist dazu gedacht, schön formatierte Texte in einfachen TXT-Dateien zu erstellen. Wenn wir unsere Dokumente in Markdown erstellen, erscheint die Kombination Markdown – Git natürlich.

Und alles wäre gut, und an dieser Stelle könnte man einen Punkt setzen, wenn nicht unser zweites Kriterium wäre: „Wir benötigen ein Dokument in einem bestimmten Format, mit den Attributen des Corporate Designs, erstellt nach einer bestimmten Vorlage“ (und wir hatten zu Beginn vereinbart, dass dies MS Word sein wird). Das heißt, wenn wir beschlossen haben, Markdown zu verwenden, müssen wir diese Datei irgendwie in das erforderliche .docx-Format umwandeln.

Es gibt Konvertierungsprogramme zwischen verschiedenen Formaten, zum Beispiel, Pandoc.
Sie können die Markdown-Datei mit diesem Programm in das .docx-Format konvertieren.
Aber man muss dennoch verstehen, dass erstens nicht alles, was in Markdown vorhanden ist, in MS Word konvertiert wird, und zweitens, dass MS Word ein ganzes Land im Vergleich zur schlichten, aber dennoch kleinen Stadt Markdown ist. Es gibt eine enorme Menge an Funktionen in Word, die in keiner Form in Markdown vorhanden sind. Man kann nicht einfach so mit bestimmten Schlüsseln Pandoc verwenden, um Ihr Markdown-Format in das gewünschte MS Word-Format zu konvertieren. Daher muss man in der Regel nach der Konvertierung das resultierende .docx-Dokument manuell „nachbearbeiten“, was wiederum zeitaufwändig sein kann und zu Fehlern führen kann.

Wenn wir ein Skript schreiben könnten, das automatisch das ergänzt, was Pandoc nicht geschafft hat – das wäre die ideale Lösung.

Aufgrund der Nicht-Identität der Funktionen von MS Word und Markdown insgesamt halte ich es für unmöglich, diese Aufgabe zu lösen, aber ist es möglich, dies auf spezifische Situationen und Anforderungen anzuwenden? Meine Erfahrung hat gezeigt, dass ja, es ist möglich, und wahrscheinlich ist es für viele oder vielleicht sogar die meisten Situationen machbar.

Lösung einer spezifischen Aufgabe

In meinem Fall musste ich nach der Konvertierung der Datei mit Pandoc manuell zusätzliche Bearbeitungen an den Dateien vornehmen, nämlich

• Felder mit automatischer Nummerierung der Überschriften (caption) für Tabellen und Bilder in Word hinzuzufügen
• das Format für Tabellen zu ändern

Ich habe nicht herausgefunden, wie das mit den standardmäßigen (Pandoc) oder bekannten Mitteln gemacht werden kann. Daher habe ich ein Python-Skript mit pywin32 -Paket verwendet. Das Ergebnis war eine vollständige Automatisierung. Jetzt kann ich meine Markdown-Datei mit einem Befehl in die gewünschte Form des MS Word-Dokuments konvertieren.

Siehe Details hier.

Hinweis

In diesem Beispiel verwandele ich natürlich eine abstrakte Markdown-Datei, aber derselbe Ansatz wurde auf ein "Kampfdokument" angewendet, und das Ergebnis war praktisch dasselbe MS Word-Dokument, das wir zuvor durch manuelles Formatieren erhalten haben.

Insgesamt erhalten wir mit pywin32 nahezu die vollständige Kontrolle über das MS Word-Dokument, was es uns ermöglicht, dieses zu ändern und in das Format zu bringen, das Ihr Unternehmensstandard verlangt. Natürlich hätten diese Ziele auch mit anderen Tools, wie z.B. VBA-Makros, erreicht werden können, aber ich fand es einfacher, Python zu verwenden.

Die kurze Formel dieses Ansatzes lautet:

Markdown + Git -- (etwas) --> MS Word

Es ist nicht so wichtig, was "etwas" ist. In meinem Fall war es Pandoc und Python mit pywin32. Vielleicht haben Sie andere Vorlieben, aber wichtig ist, dass es möglich ist. Das ist die zentrale Botschaft dieses Artikels.

Zusammengefasst ist die Idee, dass Sie mit diesem Ansatz nur mit der Markdown-Datei arbeiten und Git zur Organisation der Zusammenarbeit und zur Versionierung nutzen, und nur bei Bedarf (zum Beispiel, um die Dokumentation dem Kunden zur Verfügung zu stellen) automatisch die Datei im benötigten Format (zum Beispiel MS Word) erstellen.

Prozess

Ich denke, für viele ist die oben angegebene Formel ausreichend, um zu verstehen, wie der Prozess der Dokumentation nun organisiert werden kann. Dennoch orientiere ich mich normalerweise an Netzwerktechnikern, deswegen werde ich grob zeigen, wie der Arbeitsprozess jetzt aussehen kann und wie sich dies vom Ansatz des Editierens von MS Word-Dateien unterscheidet.

Zur Klarheit wählen wir GitHub als Plattform zur Arbeit mit Git. Dann sollten Sie ein Repository erstellen und die Markdown-Datei oder -Dateien, mit denen Sie arbeiten möchten, im Master-Branch ablegen.

Wir werden einen einfachen Prozess basierend auf dem "GitHub Flow" betrachten. Eine Beschreibung davon finden Sie sowohl im Internet als auch auf Habr.

Angenommen, an der Dokumentation arbeiten vier Personen und Sie sind einer davon. Dann werden vier zusätzliche Branches mit beispielsweise den Namen dieser Personen erstellt. Jeder arbeitet lokal in seinem Branch und nimmt Änderungen mit allen erforderlichen git-Befehlen vor..

Nachdem Sie einen bestimmten abgeschlossenen Arbeitsabschnitt erledigt haben, erstellen Sie eine Pull-Request und initiieren damit die Diskussion über Ihre Änderungen. Möglicherweise stellt sich während der Diskussion heraus, dass Sie noch etwas hinzufügen oder ändern müssen. In diesem Fall nehmen Sie die erforderlichen Änderungen vor und erstellen eine zusätzliche Pull-Request. Letztendlich werden Ihre Änderungen akzeptiert und mit dem Master-Branch zusammengeführt (merge) oder abgelehnt.

Natürlich ist dies eine recht allgemeine Beschreibung. Ich empfehle, um einen detaillierten Prozess zu erstellen, sich an Ihre Entwickler zu wenden oder Fachleute zu finden. Aber ich möchte anmerken, dass die Einstiegshürde bei Git ziemlich niedrig ist. Das bedeutet nicht, dass das Protokoll einfach ist, aber Sie können mit etwas Einfachem beginnen. Wenn Sie absolut keine Kenntnisse haben, denke ich, dass Sie mit ein paar Stunden oder vielleicht Tagen für das Lernen und die Einrichtung beginnen können, es zu verwenden.

Welchen Nutzen hat dieser Ansatz im Vergleich zu dem Prozess, der im obigen Beispiel beschrieben wurde?

Tatsächlich sind die Prozesse ziemlich ähnlich, Sie haben einfach

Datei kopieren -> Branch erstellen
Text in die endgültige Datei kopieren -> Zusammenführen (merge)
Letzte Änderungen zu sich holen -> git pull/fetch
Diskussion per E-Mail -> Pull-Requests
Track-Modus -> git diff
Letzte genehmigte Version -> Master-Branch
Backup (Kopieren auf einen Remote-Server) -> git push
…

So haben Sie alles automatisiert, was Sie ohnehin manuell tun mussten.

Auf einer höheren Ebene ermöglicht es Ihnen,

• einen klaren, einfachen und kontrollierten Änderungsprozess für die Dokumentation zu erstellen.
• Da Sie das endgültige Dokument (in unserem Beispiel MS Word) automatisch erstellen, verringert sich die Wahrscheinlichkeit von Formatierungsfehlern.

Hinweis

In Anbetracht des oben Gesagten denke ich, ist es offensichtlich, dass selbst wenn Sie alleine an der Dokumentation arbeiten, die Verwendung von Git Ihre Arbeit erheblich erleichtern kann.

All dies verbessert die Qualität der Dokumentation und reduziert die Zeit für deren Erstellung. Und noch ein kleiner Bonus – Sie lernen Git, was Ihnen bei der Automatisierung Ihres Netzwerks helfen wird 🙂.

Wie stellen Sie auf den neuen Prozess um?

Zu Beginn des Artikels habe ich geschrieben, dass Sie bereits morgen nach dem neuen Ansatz arbeiten können. Wie bringen Sie Ihre Arbeit in neue Bahnen?

Hier ist eine Schritt-für-Schritt-Anleitung, die Sie wahrscheinlich befolgen müssen:

• Wenn Ihr Dokument sehr groß ist, teilen Sie es in Teile auf.
• Konvertieren Sie jeden Teil in Markdown (zum Beispiel mit Pandoc)
• Installieren Sie einen der Markdown-Editoren (ich benutze Typora)
• Sie müssen wahrscheinlich das Format der erstellten Markdown-Dokumente anpassen
• Beginnen Sie, den in dem vorherigen Kapitel beschriebenen Prozess anzuwenden
• Beginnen Sie parallel damit, das Konvertierungsskript an Ihre Aufgabe anzupassen (oder erstellen Sie etwas Eigenes)

Sie müssen nicht warten, bis Sie den Konvertierungsmechanismus Markdown → gewünschtes Dokumentenformat perfekt erstellt und debuggt haben. Selbst wenn es Ihnen nicht gelingt, das Verfahren zur Automatisierung Ihrer Markdown-Dateien schnell vollständig zu automatisieren, können Sie es dennoch in irgendeiner Form mit Pandoc durchführen und dann manuell an das Endergebnis anpassen. Normalerweise müssen Sie das nicht oft tun, sondern nur am Ende bestimmter Phasen, und diese Handarbeit, obwohl unbequem, ist meiner Meinung nach in der Debugging-Phase durchaus akzeptabel und sollte den Prozess nicht stark «verlangsamen».

Alles andere (Markdown, Git, Pandoc, Typora) ist bereits bereit und erfordert keine besonderen Anstrengungen oder Zeit, um damit zu arbeiten.

Quelle: habr.com