Használjon GIT-et a dokumentáció készítésekor

Néha nemcsak a dokumentáció maga, hanem a készítése is kritikus lehet. Például, bizonyos projektek esetében a munka jelentős része a dokumentáció előkészítésével kapcsolatos, és a hibás folyamatok hibákhoz, sőt, információvesztéshez vezethetnek, ami idő- és haszonveszteséget is okozhat. De még ha ez a téma nem is a munka középpontjában áll, a megfelelő folyamat javíthatja a dokumentum minőségét, és időt takaríthat meg.

A bemutatott megközelítés konkrét megvalósításával, alacsony belépési küszöböt mutat. Technikai értelemben már holnap elkezdheti az új módszer alkalmazását.

Lépjünk át a kitűzött feladatra: írjunk egy XDP mechanizmust SYN cookie-kkal.

Számára szükséges egy dokumentum vagy dokumentumok halmazának létrehozása. Lehet ez projekt dokumentáció vagy a hálózatának naplózása, vagy valami egyszerűbb, például a cég vagy az osztály folyamatait kell leírnia. Röviden, bármilyen dokumentumról vagy dokumentumhalmazról van szó, amely tartalmaz szöveget, képeket, táblázatokat... Nehezítjük a feladatot azzal, hogy

1. ez a munka közös erőfeszítést igényel, csoportok, vagy több csoport alkalmazottainak együttműködését
2. az eredményül kapott dokumentumnak egy meghatározott formátumban kell lennie, a vállalati arculati attribútumokkal, egy meghatározott sablon alapján készülve. Határozottság kedvéért azt fogjuk feltételezni, hogy ez egy MS Word (.docx) dokumentum

10 éve a megközelítés egyértelmű lenne: létrehozunk egy vagy több MS Word dokumentumot, és valamilyen módon szerveznénk a módosítások folyamatát.

Ez a megközelítés továbbra is érvényben van. A nagy integrátorok is használják projekt dokumentáció készítésekor. De intuitív módon nyilvánvaló, hogy ha valóban intenzíven dolgozik a dokumentumon, sok módosítással és megbeszéléssel, hosszú időn keresztül, ez a megközelítés nem túl kényelmes.

támadásra

Én is erőteljesen tapasztaltam ezt a problémát, amikor egy nagy integrátornál dolgoztam. A projekt dokumentáció módosításának folyamata a következő volt:

1. a mérnök letölti az utolsó verziójú MS Word (.docx) dokumentumot
2. megváltoztatja a nevet
3. változtatásokat hajt végre az áttekintési módban
4. a módosított dokumentumot elküldi az építésznek
5. szintén elküldi az összes módosítást a megjegyzésekkel
6. az építész elemzi a változtatásokat
7. ha minden rendben van, átmásolja a módosításokat az utolsó verzió fájlba, megváltoztatja a verziót, és közzéteszi a közös erőforráson
8. Ha bármilyen észrevétel merül fel, akkor megbeszélés (email vagy találkozók) kezdeményeződik.
9. Konszenzus születik.
10. Ezután a 3-9. pontok következnek.

Míg a munkafolyamat nem volt intenzív, valahogy működött. De egy idő után ez a folyamat a projekt szűk keresztmetszetévé vált, ami problémákhoz vezetett. Az a helyzet, hogy minden rosszul megy, amint a változtatások gyakran és egyszerre több csapat által történnek.

Amikor átálltunk az előzetes tesztelési szakaszra, különböző problémák kezdtek megjelenni, és bár apróságokról volt szó, a dokumentációt gyakran kellett módosítani - négy különböző csapat, naponta, szinte egyszerre, megbeszélésekkel. Mindezek a változások egy mérnök - építész - által érkeztek. A projekt tervfájl óriási volt, és ennek következtében az építész a sok másolással és szerkesztéssel járó rutinfeladatokkal volt elfoglalva, sok hibát vétett, mindent újra kellett ellenőrizni, újraküldeni, és összességében ez közel állt a káoszhoz.

Ebben az esetben a dokumentummal való munka MS Word megközelítése nagy nehézségeket okozott és problémákat teremtett.

Git, Markdown

A fent említett problémával szembesülve elkezdtem kutatni ezt a kérdést.
Láttam, hogy egyre népszerűbbé válik a használata Markdown együtt Konténerizálás dokumentumok létrehozásakor.

A Git egy fejlesztőeszköz. De miért ne használhatnánk a dokumentálási folyamatra is? Ebben az esetben a többfelhasználós munka kérdése megoldódik. De ahhoz, hogy a Git összes lehetőségét teljes mértékben kihasználhassuk, szöveges dokumentumformátumra van szükségünk, és más eszközt kell keresnünk, amely nem MS Word, és ezekre a célokra a Markdown kiválóan alkalmas.

A Markdown egy egyszerű szöveges jelölőnyelv. Szép formázású szövegek létrehozására szolgál sima TXT fájlokban. Ha Markdown formátumban készítjük el a dokumentumainkat, akkor a Markdown - Git összekapcsolása természetesnek tűnik.

Mindez rendben van, és itt akár meg is állhatnánk, ha nem lenne a második feltételünk: "a kimenetnek egy bizonyos formátumban kell lennie, vállalati stílusjegyekkel, egy meghatározott sablon alapján" (előre megállapodtunk abban, hogy ez MS Word lesz). Tehát, ha úgy döntöttünk, hogy Markdown-t használunk, akkor valahogy át kell alakítanunk ezt a fájlt a kívánt .docx formátumba.

Vannak programok, amelyek különböző formátumok között konvertálnak, például, Pandoc.
Ezzel a programmal Markdown fájlt konvertálhat .docx formátumba.
De mégis, érdemes megérteni, hogy egyrészt nem minden, ami Markdown-ban van, lesz konvertálva MS Word-be, másrészt MS Word egy egész ország a viszonylag egyszerű, de mégis kisvárosként működő Markdownhoz képest. Rengeteg olyan dolog van Word-ben, ami sehol sincs Markdown formátumban. Nem lehet csak úgy, egyes kulcsokkal Pandoc segítségével átkonvertálni a Markdown formátumot a kívánt MS Word kinézetre. Szóval általában a konvertálás után kézzel kell "finomítani" a kapott .docx dokumentumot, ami megintcsak időigényes lehet és hibákhoz vezethet.

Ha tudnánk írni egy szkriptet, ami automatikusan "befejezné" azt, amivel Pandoc nem boldogult — ez lenne az ideális megoldás.

Tekintettel arra, hogy az MS Word és Markdown funkciói nem azonosak, ezt a feladatot általánosságban véve lehetetlennek gondolom, de lehet-e ezt megoldani konkrét helyzetekhez, konkrét követelményekhez? Tapasztalatom alapján igen, lehet, és valószínűleg sok, vagy talán a legtöbb helyzetben lehetséges.

Egyedi feladat megoldása

Tehát az én esetemben, miután a fájlt Pandoc segítségével konvertáltam, manuálisan kellett további feldolgozást végeznem, mégpedig

• címsorok (caption) automatikus számozásával ellátott mezőket kell hozzáadni Word-ben a táblázatoknak és képeknek
• a táblázatok stílusát módosítani

Nem találtam, hogyan lehet ezt megtenni a standard (Pandoc) vagy ismert eszközökkel. Ezért egy Python szkriptet alkalmaztam a pywin32 csomaggal. Ennek eredményeként teljes automatizálást kaptam. Most már egy parancs segítségével tudom konvertálni a Markdown fájlomat a kívánt MS Word dokumentum formátumra.

Nézze meg a részleteket itt.

Megjegyzés

Ebben a példában természetesen egy absztrakt Markdown fájlt alakítok át, de pontosan ugyanazt a megközelítést alkalmaztam egy 'éles' dokumentumra is, és eredményként gyakorlatilag pontosan ugyanazt a MS Word dokumentumot kaptam, mint amit korábban manuális formázással készítettünk.

Összességében a pywin32 segítségével szinte teljes irányítást szerzünk a MS Word dokumentum felett, ami lehetővé teszi, hogy átformáljuk azt, és a vállalati szabványoknak megfelelő megjelenést érjünk el. Természetesen ezek a célok más eszközökkel, például VBA makrókkal is elérhetők lettek volna, de számomra kényelmesebb volt a python használata.

A megközelítés rövid képlete:

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

Nem annyira fontos, hogy mi a 'valami'. Az én esetemben ez a Pandoc és a python a pywin32-vel volt. Lehet, hogy neked más preferenciáid vannak, de fontos, hogy ez lehetséges. És ez a legfőbb üzenete ennek a cikknek.

Összefoglalva, az ötlet az, hogy ezzel a megközelítéssel csak a Markdown fájllal dolgozol, és a Git segítségével szervezed a közös munkát és a verziókezelést, és csak szükség esetén (például a dokumentáció ügyfélnek való átadása érdekében) automatikusan létrehozol egy szükséges formátumú fájlt (például MS Word-t).

Folyamat

Azt hiszem, sokak számára a fenti képlet elegendő ahhoz, hogy megértsék, hogyan lehet most a dokumentációval dolgozást megszervezni. De azért általában a hálózati mérnökökre összpontosítok, ezért vázoltan bemutatom, hogyan is nézhet ki most a munka folyamata, és miben különbözik a MS Word fájlok szerkesztésével való megközelítéstől.

A pontosabb érthetőség kedvéért a Git munkához a GitHub platformot választjuk. Ezért létre kell hoznod egy tárolót és a master ágon elhelyezni a Markdown fájlt vagy fájlokat, amelyekkel dolgozni tervezel.

Egy egyszerű folyamatot fogunk megvizsgálni, amely a 'github flow' alapjain nyugszik. Ennek leírását megtalálhatod, akár az interneten, akár a Habrán.

Tegyük fel, hogy négy ember dolgozik a dokumentáción, és te az egyik közülük vagy. Ekkor négy további ágat (branch) kell létrehozni, például ezeknek az embereknek a neveivel. Mindenki helyben, a saját ágán dolgozik, és minden szükséges változtatást elvégez a git parancsokkal.

A munka befejezésével pull request-et hoz létre, ezzel elindítva a módosításai megbeszélését. Lehet, hogy a beszélgetés során kiderül, hogy valami újabbat kell hozzáadnia vagy módosítania. Ebben az esetben elvégzi a szükséges változtatásokat, és létrehozza a további pull request-et. Végül a módosításait elfogadják és egyesítik (merge) a master ággal (vagy elutasítják).

Természetesen ez egy meglehetősen általános leírás. Javaslom, hogy a részletes folyamat kidolgozása érdekében forduljon a fejlesztői csapatához, vagy keressen meg tapasztalt szakembereket. De szeretném megjegyezni, hogy a Git használatának küszöbértéke meglehetősen alacsony. Ez nem jelenti azt, hogy a protokoll egyszerű, de a legegyszerűbb feladatokat könnyen el tudja kezdeni. Ha teljesen járatlan a területen, úgy gondolom, néhány óra vagy akár nap eltöltésével a tanulásra és telepítésre, már használhatja is.

Milyen haszna van ennek a megközelítésnek a folyamat példájával összehasonlítva?

Valójában a folyamatok meglehetősen hasonlóak, csak kicserélte a

fájl másolása -> ág (branch) létrehozása
szöveg átmásolása a végső fájlba -> egyesítés (merge)
a legutóbbi módosítások másolása -> git pull/fetch
megbeszélés a levelezésben -> pull requestek
nyomkövető mód -> git diff
a legutolsó jóváhagyott verzió -> master ág
biztonsági mentés (másolás távoli szerverre) -> git push
…

Így automatizálta az összes olyan feladatot, amit eddig kézi úton kellett elvégeznie.

Magasabb szinten ez lehetővé teszi, hogy

• egy világos, egyszerű és kontrollált dokumentációs változási folyamatot hozzon létre
• mivel a végső dokumentumot (példánkban MS Word) automatikusan hozza létre, ez csökkenti a formázással kapcsolatos hibák lehetőségét.

Megjegyzés

A fenti megjegyzések alapján úgy gondolom, nyilvánvaló, hogy még ha egyedül dolgozik is a dokumentáción, a Git használata jelentősen megkönnyítheti a munkáját.

Ez mind növeli a dokumentáció minőségét és csökkenti az elkészítési időt. És egy kis bónuszként — meg fogja tanulni a Git-et, ami segíthet az hálózata automatizálásában 🙂

Hogyan lehet átállni az új folyamatra?

A cikk elején írtam, hogy már holnap el kezdheti az új módszerek alkalmazását. Hogyan terelheti a munkáját új irányba?

Íme a lépések sorrendje, amelyeket valószínűleg végre kell hajtania:

• ha a dokumentuma nagyon nagy, bontsa fel részekre
• Konvertáljon minden részt Markdownba (például a Pandoc segítségével)
• Telepítse az egyik Markdown-szerkesztőt (én a következőt használom: Typora)
• Valószínűleg ki kell igazítania a létrehozott Markdown-dokumentumok formázását
• Kezdje el alkalmazni a folyamatot, amelyet az előző fejezetben leírtunk
• Párhuzamosan kezdje el módosítani a konvertáló scriptet a saját feladatához (vagy hozzon létre valami újat)

Nem szükséges megvárnia, amíg tökéletesen létrehozza és debugolja a Markdown -> a kívánt dokumentumtípusra való konvertálás mechanizmusát. Az a helyzet, hogy még ha nem is sikerül gyorsan teljesen automatizálni a Markdown fájlok átalakításának eljárását, akkor is képes lesz valamilyen formában ezt megtenni a Pandoc segítségével, és később manuálisan eljutni a végső formához. Általában erre nincs szüksége, mert csak egyes lépések végén kell megtenni, és ez a kézi munka, bármennyire is kényelmetlen, véleményem szerint teljesen elfogadható a debugolási szakaszban, és nem kell, hogy lassítsa a folyamatot.

Minden egyéb (Markdown, Git, Pandoc, Typora) már készen áll, és nem igényel különösebb erőfeszítést vagy időt az elinduláshoz.

Forrás: habr.com