{"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\/nl\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"Gebruik GIT bij documentatie","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Soms kan niet alleen de documentatie zelf, maar ook het proces om eraan te werken kritiek zijn. Bijvoorbeeld, in het geval van projecten is een groot deel van het werk verbonden aan het voorbereiden van documentatie, en een verkeerd proces kan leiden tot fouten en zelfs tot verlies van informatie, en dus tot verlies van tijd en winst. Maar zelfs als dit onderwerp niet centraal staat in uw werk en aan de rand ligt, kan een juist proces nog steeds de kwaliteit van het document verbeteren en u tijd besparen.<\/p>\n

De benadering die hier wordt gepresenteerd, met een voorbeeld van een concrete implementatie<\/a><\/noindex>, heeft een lage instapdrempel. Technisch gezien kunt u morgen al anders gaan werken.
\n<\/a><\/noindex><\/p>\n

Taakstelling<\/h3>\n

\nU moet een document of een set documenten maken. Misschien is dit projectdocumentatie of het documenteren van uw netwerk, of iets eenvoudiger, bijvoorbeeld het beschrijven van processen binnen uw bedrijf of afdeling. Kortom, het gaat om elk document of set documenten met tekst, afbeeldingen, tabellen... Laten we de taak compliceren door te zeggen dat <\/p>\n

    \n
  1. dit werk samenwerking vereist, de inspanningen van een groep of meerdere groepen medewerkers<\/li>\n
  2. en uiteindelijk wilt u een document in een bepaald formaat, met kenmerken van de huisstijl, dat volgens een bepaalde sjabloon is gemaakt. Voor de duidelijkheid nemen we aan dat het een MS Word (.docx) document is.<\/li>\n<\/ol>\n

    \nTien jaar geleden zou de aanpak eenduidig zijn geweest: we zouden een MS Word document of documenten hebben gemaakt en op de een of andere manier het werk van wijziging hebben georganiseerd. <\/p>\n

    En deze aanpak is nog steeds van kracht. Deze wordt ook gebruikt door grote integratoren bij het opstellen van projectdocumentatie. Maar het is intu\u00eftief begrijpelijk dat, als u daadwerkelijk intensief met veel wijzigingen en discussies gedurende langere tijd aan een document werkt, deze aanpak niet erg handig is.<\/p>\n

    Voorbeeld<\/b><\/p>\n

    Ik heb deze kwestie vrij scherp ervaren terwijl ik bij een grote integrator werkte. Het proces van het wijzigen van projectdocumentatie was als volgt:<\/p>\n

      \n
    1. de ingenieur downloadt de laatste versie van het MS Word (.docx) document<\/li>\n
    2. verandert de titel<\/li>\n
    3. brengt wijzigingen aan in de track-modus<\/li>\n
    4. stuurt het document met wijzigingen naar de architect<\/li>\n
    5. stuurt ook een lijst van alle correcties met opmerkingen<\/li>\n
    6. de architect analyseert de wijzigingen<\/li>\n
    7. als alles goed is, kopieert hij deze wijzigingen naar het bestand met de laatste versie, verandert de versie en plaatst het op de openbare resource<\/li>\n
    8. Als er opmerkingen zijn, wordt er een discussie ge\u00efnitieerd (per e-mail of vergaderingen)<\/li>\n
    9. Er wordt consensus bereikt<\/li>\n
    10. Vervolgens punten 3-9<\/li>\n<\/ol>\n

      \nHoewel het werk niet intensief was, werkte het enige tijd wel, maar op een gegeven moment werd dit proces de bottleneck van het hele project en leidde het tot problemen. Het probleem is dat alles slecht wordt zodra wijzigingen vaak en tegelijkertijd door meerdere teams worden aangebracht.<\/p>\n

      Toen we in de fase van voorlopige testing kwamen, begonnen verschillende probleempjes zich te vormen, en hoewel het om kleine dingen ging, moesten we de documentatie vaak veranderen - vier verschillende teams, iedere dag, praktisch tegelijkertijd, met besprekingen. Al deze wijzigingen gingen via \u00e9\u00e9n engineer - de architect. Het projectontwerp was enorm, en als gevolg daarvan was de architect overladen met routinematige taken die veel kopieer- en bewerkingswerk vereisten, waardoor hij veel fouten maakte, alles opnieuw moest controleren en opnieuw moest sturen, en in het algemeen was dit dicht bij chaos. <\/p>\n

      In dit geval werkte deze aanpak, die gebaseerd was op het MS Word-document, met veel problemen en leidde tot complicaties.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nToen ik geconfronteerd werd met het probleem zoals beschreven in het bovenstaande voorbeeld, begon ik dit onderwerp te onderzoeken.
      \nIk merkte dat het gebruik van       Markdown<\/a><\/noindex> in samenwerking met Git<\/a><\/noindex> bij het maken van documenten steeds populairder werd.<\/p>\n

      Git is een ontwikkelingsinstrument. Maar waarom zouden we het niet gebruiken voor het documentatieproces? In dit geval is de vraag over samenwerking opgelost. Maar om de mogelijkheden van Git volledig te benutten, hebben we een tekstformaat nodig, we moeten een ander instrument vinden dan MS Word, en Markdown is daarvoor uitstekend geschikt. <\/p>\n

      Markdown is een eenvoudige opmaaktaal. Het is bedoeld voor het maken van mooi opgemaakte teksten in standaard TXT-bestanden. Als we onze documenten in Markdown maken, lijkt de combinatie Markdown - Git vanzelfsprekend.<\/p>\n

      En alles zou goed zijn, en op dit punt zou je een punt kunnen zetten, als het niet was voor onze tweede voorwaarde: \"we hebben een document nodig in een bepaald formaat, met attributen van de huisstijl, gemaakt volgens een bepaald sjabloon\" (en we waren in het begin overeengekomen dat dit een MS Word-document zou zijn). Dat wil zeggen, als we besloten hebben om Markdown te gebruiken, moeten we deze file op een of andere manier omzetten naar .docx in de vereiste vorm.<\/p>\n

      Er zijn conversieprogramma's tussen verschillende formaten, bijvoorbeeld, Pandoc<\/a><\/noindex>.
      \nU kunt een Markdown-bestand naar het .docx-formaat converteren met dit programma.
      \nMaar nogmaals, het moet worden begrepen dat, ten eerste, niet alles wat er in Markdown is, zal worden geconverteerd naar MS Word en, ten tweede, MS Word is een heel land vergeleken met de compacte, maar toch stad, Markdown. Er is een enorm aantal dingen die in Word bestaan en niet in enige vorm in Markdown. Je kunt je Markdown-indeling niet gewoon zomaar met bepaalde sleutelwoorden van Pandoc naar de gewenste MS Word-vorm converteren. Dus meestal, na de conversie, moet je het verkregen .docx-document handmatig \"afmaken\", wat opnieuw tijdrovend kan zijn en tot fouten kan leiden.<\/p>\n

      Als we een script konden schrijven dat automatisch zou \"afmaken\" wat Pandoc niet kon, zou dat de ideale oplossing zijn.<\/p>\n

      Gezien de niet-idem functionaliteit van MS Word en Markdown, denk ik dat het in het algemeen onmogelijk is om deze taak op te lossen, maar is het mogelijk om dit toe te passen op specifieke situaties, specifieke vereisten? Mijn ervaring heeft me laten zien dat ja, het kan en waarschijnlijk is het mogelijk voor velen, of misschien zelfs de meeste situaties. <\/p>\n

      Oplossing van een specifieke taak<\/h3>\n

      \nDus, in mijn geval, na de conversie van het bestand met behulp van Pandoc, moest ik handmatig aanvullende verwerking van de bestanden doen, namelijk,<\/p>\n