Verwenden Sie GIT zur Dokumentation

Manchmal kann nicht nur die Dokumentation selbst, sondern auch der Prozess, der zu ihrer Erstellung führt, entscheidend sein. Insbesondere bei Projekten ist ein großer Teil der Arbeit mit der Vorbereitung der Dokumentation verbunden. Ein falscher Prozess kann zu Fehlern und sogar zum Verlust von Informationen führen, was wiederum Zeit und Geld kosten kann. Selbst wenn dieses Thema nicht zentral für Ihre Arbeit ist und nur am Rande behandelt wird, kann ein richtiger Prozess trotzdem die Qualität der Dokumente verbessern und Ihnen Zeit sparen.

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

Problemstellung

Sie müssen ein Dokument oder eine Dokumentensammlung erstellen. Dies könnte Projekt-Dokumentation oder Protokollierung Ihres Netzwerks sein, oder etwas Einfacheres, beispielsweise die Beschreibung von Prozessen in Ihrem Unternehmen oder in Ihrer Abteilung. Kurz gesagt, es geht um jedes Dokument oder jede Dokumentensammlung, die Texte, Bilder und Tabellen enthält… Wir erschweren die Aufgabe damit, dass

1. diese Arbeit gemeinschaftliches Engagement erfordert, das Zusammenspiel einer Gruppe oder mehrerer Gruppen von Mitarbeitern.
2. Am Ende möchten Sie ein Dokument in einem bestimmten Format mit den Attributen des Corporate Designs, erstellt nach einer bestimmten Vorlage, haben. Zur besseren Verständlichkeit nehmen wir an, dass es sich um MS Word (.docx) handelt.

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

Und dieser Ansatz gilt nach wie vor. Er wird auch von großen Integratoren verwendet, wenn sie Projektdokumentationen erstellen. Aber es ist intuitiv klar, dass dieser Ansatz nicht sehr bequem ist, wenn Sie tatsächlich intensiv über einen längeren Zeitraum an einem Dokument mit vielen Änderungen und Diskussionen arbeiten.

Beispiel

Ich habe dieses Problem deutlich gespürt, als ich bei 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 Änderungsmodus vor.
4. Schickt das Dokument mit den Änderungen an den Architekten.
5. Sendet auch eine Liste aller Korrekturen mit Anmerkungen.
6. Der Architekt analysiert die Änderungen.
7. Wenn alles gut geht, werden die Datenänderungen in die Datei der neuesten Version kopiert, die Version wird geändert und auf die gemeinsame Ressource hochgeladen.
8. Falls es Anmerkungen gibt, wird eine Diskussion eingeleitet (per E-Mail oder in Meetings).
9. Ein Konsens wird erreicht.
10. Dann folgen die Punkte 3 bis 9.

Solange die Arbeit nicht intensiv war, funktionierte es mehr oder weniger. Doch zu einem bestimmten Zeitpunkt wurde dieser Prozess zum Engpass des gesamten Projekts und führte zu Problemen. Es stellt sich heraus, dass alles schlecht wird, sobald Änderungen häufig und gleichzeitig von mehreren Teams durchgeführt werden.

Als wir in die Phase der Vorausstestung übergingen, traten verschiedene kleine Probleme auf. Obwohl sie nur geringfügig waren, musste die Dokumentation häufig aktualisiert werden – vier verschiedene Teams, die täglich praktisch gleichzeitig arbeiteten und diskutierten. Alle diese Änderungen liefen über einen Ingenieur – den Architekten. Die Projektentwurfsdatei war riesig, und daher war der Architekt mit der routinemäßigen Arbeit, die viel Kopieren und Bearbeiten umfasste, überlastet. Dadurch machte er viele Fehler und es musste alles ständig überprüft und erneut gesendet werden. Insgesamt war es nahe am Chaos.

In diesem Fall hat dieser Ansatz, die Bearbeitung eines MS Word-Dokuments, mit großem Aufwand funktioniert und Probleme verursacht.

Git, Markdown

Als ich auf das im obigen Beispiel beschriebene Problem stieß, begann ich, das Thema näher zu untersuchen.
Ich stellte fest, dass die Verwendung von Markdown immer beliebter wird Git bei der Erstellung von Dokumenten.

Git ist ein Entwicklungstool. Aber warum nicht auch für den Dokumentationsprozess nutzen? In diesem Fall wird das Thema der Zusammenarbeit gelöst. Um die Möglichkeiten von Git jedoch voll ausschöpfen zu können, benötigen wir ein Textformat für das Dokument und müssen ein anderes Werkzeug als MS Word finden. Dafür ist Markdown bestens geeignet.

Markdown ist eine einfache Auszeichnungssprache. Sie wurde entwickelt, um schön formatierte Texte in üblichen TXT-Dateien zu erstellen. Wenn wir unsere Dokumente in Markdown erstellen, erscheint die Kombination aus Markdown und Git ganz natürlich.

Und alles wäre gut, und an dieser Stelle könnte man einen Punkt setzen, wenn nicht unsere zweite Bedingung wäre: „Wir benötigen ein Dokument in einem bestimmten Format, mit Attributen im Corporate Design, das nach einer bestimmten Vorlage erstellt wurde“ (und wir haben zu Beginn vereinbart, dass es zu Klarheit MS Word sein wird). Das bedeutet, wenn wir uns entschieden 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 eine Markdown-Datei mit diesem Programm in das .docx-Format konvertieren.
Aber dennoch ist es wichtig zu verstehen, dass erstens nicht alles, was in Markdown vorhanden ist, in MS Word konvertiert wird, und zweitens ist MS Word ein ganzes Land im Vergleich zu der kompakten, aber dennoch übersichtlichen Stadt, die Markdown ist. Es gibt eine riesige Anzahl von Funktionen, die in Word vorhanden sind und in keiner Form in Markdown existieren. Man kann nicht einfach so mit bestimmten Optionen Pandoc verwenden, um Ihr Markdown-Format in das gewünschte MS Word-Format zu konvertieren. Daher muss man normalerweise nach der Konvertierung das erhaltene .docx-Dokument manuell „nachbearbeiten“, was wiederum zeitaufwendig sein kann und zu Fehlern führen kann.

Wäre es möglich, ein Skript zu erstellen, das automatisch alles vervollständigt, was Pandoc nicht bewältigen kann, wäre das die ideale Lösung.

Aufgrund der unterschiedlichen Funktionen von MS Word und Markdown im Allgemeinen ist es, denke ich, unmöglich, diese Aufgabe vollständig zu lösen. Aber lassen sich spezifische Situationen und Anforderungen vielleicht dennoch berücksichtigen? Meine Erfahrung zeigt, dass dies möglich ist und vermutlich für viele, wenn nicht sogar die meisten Situationen realisierbar ist.

Lösung eines spezifischen Problems

In meinem Fall musste ich nach der Konvertierung einer Datei mit Pandoc manuell zusätzliche Nachbearbeitungen vornehmen, und zwar:

• automatisch nummerierte Felder für Überschriften (caption) von Tabellen und Bildern in Word hinzuzufügen.
• das Stilformat für Tabellen zu ändern.

Ich konnte nicht herausfinden, wie man dies mit den gängigen (Pandoc) oder bekannten Mitteln erreicht. Daher habe ich ein Python-Skript mit dem Paket pywin32 angewendet. Dadurch erhielt ich eine vollständige Automatisierung. Jetzt kann ich meine Markdown-Datei mit einem einzigen Befehl in das gewünschte MS Word-Dokument konvertieren. Details ansehen

Details ansehen hier.

Hinweis

In diesem Beispiel verwandle ich natürlich eine abstrakte Markdown-Datei, aber derselbe Ansatz wurde auch auf ein «Live»-Dokument angewendet, und am Ende erhielt ich fast genau dasselbe MS Word-Dokument, das wir zuvor manuell formatiert hatten.

Mit pywin32 erhalten wir im Grunde vollständige Kontrolle über das MS Word-Dokument, was es uns ermöglicht, es so zu verändern und zu gestalten, wie es die Unternehmensstandards erfordern. Natürlich könnten dieselben Ziele auch mit anderen Werkzeugen wie z. B. VBA-Makros erreicht werden, aber für mich war es einfacher, Python zu verwenden.

Die kurze Formel für diesen Ansatz lautet:

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

Es spielt nicht so eine große Rolle, 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. Und das ist die Hauptbotschaft dieses Artikels.

Zusammenfassend ist die Idee, dass Sie mit diesem Ansatz nur mit der Markdown-Datei arbeiten und Git zur Organisation der Zusammenarbeit und zur Versionskontrolle nutzen, und nur bei Bedarf (zum Beispiel um Dokumentation an den Kunden zu liefern) automatisch die benötigte Datei im gewünschten Format (z. B. MS Word) erstellen.

Prozess

Ich denke, die oben genannte Formel reicht für viele aus, um zu verstehen, wie der Prozess der Dokumentationsarbeit jetzt organisiert werden kann. Allerdings orientiere ich mich normalerweise an Netzwerkingenieuren, daher werde ich im Großen und Ganzen zeigen, wie der Arbeitsprozess jetzt aussehen kann und wie er sich vom Ansatz mit MS Word-Dateien unterscheidet.

Um es klarzustellen, wählen wir GitHub als Plattform zur Arbeit mit Git. Sie sollten ein Repository erstellen und in der Master-Branch eine Markdown-Datei oder Dateien ablegen, mit denen Sie arbeiten möchten.

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

Angenommen, an der Dokumentation arbeiten vier Personen und Sie sind eine davon. Dann werden vier zusätzliche Branches erstellt, zum Beispiel mit den Namen dieser Personen. Jeder arbeitet lokal in seinem Branch und führt Änderungen mit allen benötigten Git-Befehlen durch..

Nachdem Sie einen bestimmten Arbeitsschritt abgeschlossen haben, erstellen Sie einen Pull-Request, um die Diskussion über Ihre Änderungen zu initiieren. Während dieser Diskussion kann sich herausstellen, dass Sie etwas hinzufügen oder ändern müssen. In diesem Fall nehmen Sie die notwendigen Anpassungen vor und erstellen einen weiteren Pull-Request. Schließlich 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, Ihre Entwickler zu konsultieren oder Leute mit Fachkenntnissen zu finden. Ich möchte jedoch darauf hinweisen, dass die Einstiegshürde in Git relativ niedrig ist. Das bedeutet nicht, dass das Protokoll einfach ist, aber Sie können mit den Grundlagen beginnen. Wenn Sie noch nichts darüber wissen, glauben Sie, dass Sie nach einigen Stunden oder vielleicht Tagen des Lernens und der Einrichtung loslegen können.

Welche Vorteile bietet dieser Ansatz im Vergleich zu dem in dem obigen Beispiel beschriebenen Prozess?

Tatsächlich sind die Prozesse ziemlich ähnlich, nur dass Sie

das Kopieren einer Datei -> das Erstellen eines Branches
das Kopieren von Text in eine endgültige Datei -> das Zusammenführen (merge)
Kopieren der letzten Änderungen auf Ihren Computer -> git pull/fetch
Diskussion im Austausch -> Pull-Anfragen
Track-Modus -> git diff
Letzte genehmigte Version -> master Branch
Backup (Kopieren auf einen entfernten Server) -> git push
…

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

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

• einen klaren, einfachen und kontrollierten Prozess für Dokumentenänderungen zu erstellen.
• Da das Enddokument (in unserem Beispiel MS Word) automatisch erstellt wird, verringert sich die Wahrscheinlichkeit von Formatierungsfehlern.

Hinweis

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

All das verbessert die Qualität der Dokumentation und verkürzt die Zeit zu ihrer Erstellung. Und ein kleiner Bonus: Sie werden Git lernen, was Ihnen bei der Automatisierung Ihres Netzwerks helfen wird 🙂

Wie wechseln Sie zu dem neuen Prozess?

Am Anfang des Artikels habe ich geschrieben, dass Sie bereits morgen nach neuen Methoden arbeiten können. Wie bringen Sie Ihre Arbeit in eine neue Bahn?

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).)
• Wahrscheinlich müssen Sie das Format der erstellten Markdown-Dokumente anpassen.
• Beginnen Sie mit dem Prozess, der im vorherigen Kapitel beschrieben wurde.
• Gleichzeitig sollten Sie das Konvertierungsskript an Ihre Aufgabe anpassen (oder etwas Eigenes erstellen).

Es ist nicht notwendig, zu warten, bis Sie den Konvertierungsmechanismus von Markdown in das gewünschte Dokument perfekt erstellt und debuggt haben. Selbst wenn es Ihnen nicht gelingt, das Verfahren zur Automatisierung der Umwandlung Ihrer Markdown-Dateien schnell vollständig zu automatisieren, können Sie es trotzdem mit Pandoc in irgendeiner Form umsetzen und anschließend manuell abrunden. Normalerweise müssen Sie dies nicht oft tun, sondern nur am Ende bestimmter Etappen, und diese manuelle Arbeit, obwohl sie unangenehm ist, 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