{"id":35419,"date":"2019-10-31T22:04:14","date_gmt":"2019-10-31T19:04:14","guid":{"rendered":"https:\/\/prohoster.info\/blog\/ispolzujte-git-pri-dokumentirovanii\/"},"modified":"2019-10-31T22:04:14","modified_gmt":"2019-10-31T19:04:14","slug":"ispolzujte-git-pri-dokumentirovanii","status":"publish","type":"post","link":"https:\/\/prohoster.info\/de\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"Verwenden Sie GIT zur Dokumentation","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Manchmal kann nicht nur die Dokumentation selbst, sondern auch der Prozess, der zu ihrer Erstellung f\u00fchrt, entscheidend sein. Insbesondere bei Projekten ist ein gro\u00dfer Teil der Arbeit mit der Vorbereitung der Dokumentation verbunden. Ein falscher Prozess kann zu Fehlern und sogar zum Verlust von Informationen f\u00fchren, was wiederum Zeit und Geld kosten kann. Selbst wenn dieses Thema nicht zentral f\u00fcr Ihre Arbeit ist und nur am Rande behandelt wird, kann ein richtiger Prozess trotzdem die Qualit\u00e4t der Dokumente verbessern und Ihnen Zeit sparen.<\/p>\n

Der hier dargestellte Ansatz, zusammen mit einem Beispiel f\u00fcr eine konkrete Umsetzung<\/a><\/noindex>, hat eine niedrige Eintrittsschwelle. Technisch gesehen k\u00f6nnen Sie bereits morgen anders arbeiten.
\n<\/a><\/noindex><\/p>\n

Problemstellung<\/h3>\n

\nSie m\u00fcssen ein Dokument oder eine Dokumentensammlung erstellen. Dies k\u00f6nnte 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\u00e4lt\u2026 Wir erschweren die Aufgabe damit, dass <\/p>\n

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

    \nVor 10 Jahren w\u00e4re der Ansatz klar gewesen: Wir h\u00e4tten ein oder mehrere MS Word-Dokumente erstellt und die Arbeit an den \u00c4nderungen entsprechend organisiert. <\/p>\n

    Und dieser Ansatz gilt nach wie vor. Er wird auch von gro\u00dfen Integratoren verwendet, wenn sie Projektdokumentationen erstellen. Aber es ist intuitiv klar, dass dieser Ansatz nicht sehr bequem ist, wenn Sie tats\u00e4chlich intensiv \u00fcber einen l\u00e4ngeren Zeitraum an einem Dokument mit vielen \u00c4nderungen und Diskussionen arbeiten.<\/p>\n

    Beispiel<\/b><\/p>\n

    Ich habe dieses Problem deutlich gesp\u00fcrt, als ich bei einem gro\u00dfen Integrator gearbeitet habe. Der Prozess zur \u00c4nderung der Projektdokumentation war folgender:<\/p>\n

      \n
    1. Der Ingenieur l\u00e4dt die neueste Version des MS Word-Dokuments (.docx) herunter.<\/li>\n
    2. \u00c4ndert den Titel.<\/li>\n
    3. Nimmt \u00c4nderungen im \u00c4nderungsmodus vor.<\/li>\n
    4. Schickt das Dokument mit den \u00c4nderungen an den Architekten.<\/li>\n
    5. Sendet auch eine Liste aller Korrekturen mit Anmerkungen.<\/li>\n
    6. Der Architekt analysiert die \u00c4nderungen.<\/li>\n
    7. Wenn alles gut geht, werden die Daten\u00e4nderungen in die Datei der neuesten Version kopiert, die Version wird ge\u00e4ndert und auf die gemeinsame Ressource hochgeladen.<\/li>\n
    8. Falls es Anmerkungen gibt, wird eine Diskussion eingeleitet (per E-Mail oder in Meetings).<\/li>\n
    9. Ein Konsens wird erreicht.<\/li>\n
    10. Dann folgen die Punkte 3 bis 9.<\/li>\n<\/ol>\n

      \nSolange 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\u00fchrte zu Problemen. Es stellt sich heraus, dass alles schlecht wird, sobald \u00c4nderungen h\u00e4ufig und gleichzeitig von mehreren Teams durchgef\u00fchrt werden.<\/p>\n

      Als wir in die Phase der Vorausstestung \u00fcbergingen, traten verschiedene kleine Probleme auf. Obwohl sie nur geringf\u00fcgig waren, musste die Dokumentation h\u00e4ufig aktualisiert werden \u2013 vier verschiedene Teams, die t\u00e4glich praktisch gleichzeitig arbeiteten und diskutierten. Alle diese \u00c4nderungen liefen \u00fcber einen Ingenieur \u2013 den Architekten. Die Projektentwurfsdatei war riesig, und daher war der Architekt mit der routinem\u00e4\u00dfigen Arbeit, die viel Kopieren und Bearbeiten umfasste, \u00fcberlastet. Dadurch machte er viele Fehler und es musste alles st\u00e4ndig \u00fcberpr\u00fcft und erneut gesendet werden. Insgesamt war es nahe am Chaos. <\/p>\n

      In diesem Fall hat dieser Ansatz, die Bearbeitung eines MS Word-Dokuments, mit gro\u00dfem Aufwand funktioniert und Probleme verursacht.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nAls ich auf das im obigen Beispiel beschriebene Problem stie\u00df, begann ich, das Thema n\u00e4her zu untersuchen.
      \nIch stellte fest, dass die Verwendung von       Markdown<\/a><\/noindex> immer beliebter wird Git<\/a><\/noindex> bei der Erstellung von Dokumenten.<\/p>\n

      Git ist ein Entwicklungstool. Aber warum nicht auch f\u00fcr den Dokumentationsprozess nutzen? In diesem Fall wird das Thema der Zusammenarbeit gel\u00f6st. Um die M\u00f6glichkeiten von Git jedoch voll aussch\u00f6pfen zu k\u00f6nnen, ben\u00f6tigen wir ein Textformat f\u00fcr das Dokument und m\u00fcssen ein anderes Werkzeug als MS Word finden. Daf\u00fcr ist Markdown bestens geeignet. <\/p>\n

      Markdown ist eine einfache Auszeichnungssprache. Sie wurde entwickelt, um sch\u00f6n formatierte Texte in \u00fcblichen TXT-Dateien zu erstellen. Wenn wir unsere Dokumente in Markdown erstellen, erscheint die Kombination aus Markdown und Git ganz nat\u00fcrlich.<\/p>\n

      Und alles w\u00e4re gut, und an dieser Stelle k\u00f6nnte man einen Punkt setzen, wenn nicht unsere zweite Bedingung w\u00e4re: \u201eWir ben\u00f6tigen ein Dokument in einem bestimmten Format, mit Attributen im Corporate Design, das nach einer bestimmten Vorlage erstellt wurde\u201c (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\u00fcssen wir diese Datei irgendwie in das erforderliche .docx-Format umwandeln.<\/p>\n

      Es gibt Konvertierungsprogramme zwischen verschiedenen Formaten, zum Beispiel Pandoc<\/a><\/noindex>.
      \nSie k\u00f6nnen eine Markdown-Datei mit diesem Programm in das .docx-Format konvertieren.
      \nAber 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 \u00fcbersichtlichen 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\u00fcnschte MS Word-Format zu konvertieren. Daher muss man normalerweise nach der Konvertierung das erhaltene .docx-Dokument manuell \u201enachbearbeiten\u201c, was wiederum zeitaufwendig sein kann und zu Fehlern f\u00fchren kann.<\/p>\n

      W\u00e4re es m\u00f6glich, ein Skript zu erstellen, das automatisch alles vervollst\u00e4ndigt, was Pandoc nicht bew\u00e4ltigen kann, w\u00e4re das die ideale L\u00f6sung.<\/p>\n

      Aufgrund der unterschiedlichen Funktionen von MS Word und Markdown im Allgemeinen ist es, denke ich, unm\u00f6glich, diese Aufgabe vollst\u00e4ndig zu l\u00f6sen. Aber lassen sich spezifische Situationen und Anforderungen vielleicht dennoch ber\u00fccksichtigen? Meine Erfahrung zeigt, dass dies m\u00f6glich ist und vermutlich f\u00fcr viele, wenn nicht sogar die meisten Situationen realisierbar ist. <\/p>\n

      L\u00f6sung eines spezifischen Problems<\/h3>\n

      \nIn meinem Fall musste ich nach der Konvertierung einer Datei mit Pandoc manuell zus\u00e4tzliche Nachbearbeitungen vornehmen, und zwar:<\/p>\n