{"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 bei der Dokumentation","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Manchmal kann nicht nur die Dokumentation selbst, sondern auch der Prozess zu ihrer Erstellung kritisch sein. Zum Beispiel ist ein gro\u00dfer Teil der Arbeit in Projekten tats\u00e4chlich mit der Erstellung von Dokumentationen verbunden, und ein falscher Prozess kann zu Fehlern und sogar zu Informationsverlust f\u00fchren, 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\u00e4t des Dokuments verbessern und Ihnen Zeit sparen.<\/p>\n

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

Aufgabenstellung<\/h3>\n

\nSie m\u00fcssen ein Dokument oder eine Dokumentensammlung erstellen. M\u00f6glicherweise handelt es sich um Projektdokumentation oder Protokollierung Ihres Netzwerks, oder um etwas Einfacheres, zum Beispiel m\u00fcssen 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 <\/p>\n

    \n
  1. diese Arbeit gemeinschaftliche Anstrengungen, die Zusammenarbeit von Gruppen oder mehreren Gruppen von Mitarbeitern erfordert<\/li>\n
  2. Am Ende m\u00f6chten 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.<\/li>\n<\/ol>\n

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

    Und dieser Ansatz ist nach wie vor g\u00fcltig. Er wird auch von gro\u00dfen Integratoren bei der Erstellung von Projektdokumentationen verwendet. Aber es ist intuitiv klar, dass, wenn Sie wirklich intensiv, mit vielen \u00c4nderungen und Diskussionen, \u00fcber l\u00e4ngere Zeit an einem Dokument arbeiten, dieser Ansatz nicht sehr praktisch ist.<\/p>\n

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

    Ich habe dieses Problem ziemlich stark gesp\u00fcrt, als ich in 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. \u00e4ndert den Titel<\/li>\n
    3. nimmt \u00c4nderungen im Track-Modus vor<\/li>\n
    4. sendet das Dokument mit den \u00c4nderungen an den Architekten<\/li>\n
    5. sendet auch eine Liste aller Korrekturen mit Kommentaren<\/li>\n
    6. der Architekt analysiert die \u00c4nderungen<\/li>\n
    7. Wenn alles gut ist, werden die \u00c4nderungen der Daten in die Datei mit der neuesten Version kopiert, die Version ge\u00e4ndert und auf die gemeinsame Ressource hochgeladen.<\/li>\n
    8. Wenn es Anmerkungen gibt, wird eine Diskussion initiiert (per E-Mail oder Meetings).<\/li>\n
    9. Es wird ein Konsens erreicht.<\/li>\n
    10. Dann die Punkte 3 \u2013 9.<\/li>\n<\/ol>\n

      \nSolange die Arbeit nicht intensiv war, hat es einigerma\u00dfen funktioniert, aber es hat trotzdem funktioniert. Doch irgendwann wurde dieser Prozess zum Engpass des gesamten Projekts und f\u00fchrte zu Problemen. Das Problem ist, dass alles schlecht wird, sobald \u00c4nderungen h\u00e4ufig und gleichzeitig von mehreren Teams vorgenommen werden.<\/p>\n

      Als wir in die Phase der Vorpr\u00fcfung \u00fcbergingen, traten verschiedene Probleme auf, und obwohl es Kleinigkeiten waren, musste die Dokumentation h\u00e4ufig ge\u00e4ndert werden \u2013 vier verschiedene Teams t\u00e4glich, praktisch gleichzeitig, mit Diskussionen. Alle diese \u00c4nderungen gingen \u00fcber einen Ingenieur \u2013 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, \u00fcberlastet, machte viele Fehler, musste alles erneut \u00fcberpr\u00fcfen und weitersenden, und im Gro\u00dfen und Ganzen war es nahe am Chaos. <\/p>\n

      In diesem Fall hat dieser Ansatz, mit dem Dokument MS Word zu arbeiten, mit gro\u00dfem Aufwand funktioniert und Probleme geschaffen.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nBei der Konfrontation mit dem oben beschriebenen Problem begann ich, diese Frage zu erforschen.
      \nIch sah, dass die Verwendung von       Markdown<\/a><\/noindex> in Kombination mit Git<\/a><\/noindex> bei der Erstellung von Dokumenten immer beliebter wird.<\/p>\n

      Git ist ein Werkzeug f\u00fcr die Entwicklung. Aber warum es nicht f\u00fcr den Dokumentationsprozess nutzen? In diesem Fall wird die Frage der Mehrbenutzerarbeit gel\u00f6st. Um jedoch die M\u00f6glichkeiten von Git voll auszusch\u00f6pfen, ben\u00f6tigen wir ein Textformat f\u00fcr das Dokument, wir m\u00fcssen ein anderes Werkzeug finden, nicht MS Word, und daf\u00fcr eignet sich Markdown hervorragend. <\/p>\n

      Markdown ist eine einfache Markup-Sprache. Sie ist dazu gedacht, sch\u00f6n formatierte Texte in einfachen TXT-Dateien zu erstellen. Wenn wir unsere Dokumente in Markdown erstellen, erscheint die Kombination Markdown \u2013 Git nat\u00fcrlich.<\/p>\n

      Und alles w\u00e4re gut, und an dieser Stelle k\u00f6nnte man einen Punkt setzen, wenn nicht unser zweites Kriterium w\u00e4re: \u201eWir ben\u00f6tigen ein Dokument in einem bestimmten Format, mit den Attributen des Corporate Designs, erstellt nach einer bestimmten Vorlage\u201c (und wir hatten zu Beginn vereinbart, dass dies MS Word sein wird). Das hei\u00dft, wenn wir beschlossen 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 die Markdown-Datei mit diesem Programm in das .docx-Format konvertieren.
      \nAber 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\u00fcsseln Pandoc verwenden, um Ihr Markdown-Format in das gew\u00fcnschte MS Word-Format zu konvertieren. Daher muss man in der Regel nach der Konvertierung das resultierende .docx-Dokument manuell \u201enachbearbeiten\u201c, was wiederum zeitaufw\u00e4ndig sein kann und zu Fehlern f\u00fchren kann.<\/p>\n

      Wenn wir ein Skript schreiben k\u00f6nnten, das automatisch das erg\u00e4nzt, was Pandoc nicht geschafft hat \u2013 das w\u00e4re die ideale L\u00f6sung.<\/p>\n

      Aufgrund der Nicht-Identit\u00e4t der Funktionen von MS Word und Markdown insgesamt halte ich es f\u00fcr unm\u00f6glich, diese Aufgabe zu l\u00f6sen, aber ist es m\u00f6glich, dies auf spezifische Situationen und Anforderungen anzuwenden? Meine Erfahrung hat gezeigt, dass ja, es ist m\u00f6glich, und wahrscheinlich ist es f\u00fcr viele oder vielleicht sogar die meisten Situationen machbar. <\/p>\n

      L\u00f6sung einer spezifischen Aufgabe<\/h3>\n

      \nIn meinem Fall musste ich nach der Konvertierung der Datei mit Pandoc manuell zus\u00e4tzliche Bearbeitungen an den Dateien vornehmen, n\u00e4mlich<\/p>\n