Użyj GIT podczas dokumentacji

Czasami nie tylko sama dokumentacja, ale także proces pracy nad nią może być krytyczny. Na przykład w przypadku projektów lwia część pracy związana jest z przygotowaniem dokumentacji, a niewłaściwy proces może prowadzić do błędów, a nawet utraty informacji, a co za tym idzie, do utraty czasu i korzyści. Ale nawet jeśli ten temat nie jest centralny w Twojej pracy i znajduje się na peryferiach, to i tak właściwy proces może poprawić jakość dokumentu i zaoszczędzić czas.

Przedstawione podejście, z przykładem konkretnej realizacji, ma niski próg wejścia. Technicznie, już jutro możesz zacząć pracować na nowo.

Sformułowanie zadania

Musisz stworzyć pewien dokument lub zestaw dokumentów. Może to być dokumentacja projektowa lub protokołowanie sieci, albo coś prostszego, na przykład musisz opisać procesy w firmie lub w swoim dziale. Generalnie chodzi o każdy dokument lub zestaw dokumentów z tekstem, obrazkami, tabelami… Utrudnimy zadanie tym, że

1. ta praca zakłada wspólny wysiłek, zaangażowanie grupy lub kilku grup pracowników
2. na wyjściu chcesz mieć dokument w określonym formacie, z atrybutami korporacyjnego stylu, stworzony według określonego szablonu. Na potrzeby tego opisu przyjmijmy, że jest to MS Word (.docx)

10 lat temu podejście byłoby jednoznaczne: stworzyliśmy by dokument MS Word lub dokumenty i w jakiś sposób zorganizowali pracę nad zmianami.

I to podejście wciąż jest aktualne. Korzystają z niego również duże integratory przy tworzeniu dokumentacji projektowej. Ale intuicyjnie wiadomo, że, jeśli naprawdę intensywnie, z wieloma poprawkami i dyskusjami, przez długi czas pracujesz nad dokumentem, to to podejście nie jest zbyt wygodne.

Przykład

Dość ostro odczułem ten problem, pracując w jednej dużej firmie integracyjnej. Proces wprowadzania zmian w dokumentacji projektowej wyglądał następująco:

1. inżynier pobiera najnowszą wersję dokumentu MS Word (.docx)
2. zmienia tytuł
3. wprowadza poprawki w trybie track
4. wysyła dokument z poprawkami do architekta
5. także wysyła listę wszystkich poprawek z komentarzami
6. architekt analizuje zmiany
7. jeśli wszystko jest w porządku, to kopiuje zmiany danych do pliku z ostatnią wersją, zmienia wersję, umieszcza na wspólnym zasobie
8. jeśli są uwagi, to inicjowana jest dyskusja (e-mail lub spotkania)
9. osiągnięto konsensus
10. dalej punkty 3 – 9

Dopóki praca nie była intensywna, to jakoś to działało. Ale w pewnym momencie ten proces stał się wąskim gardłem całego projektu i doprowadził do problemów. Chodzi o to, że wszystko staje się źle, gdy zmiany są wprowadzane często i jednocześnie przez kilka zespołów.

Tak więc, gdy przeszliśmy do etapu wstępnego testowania, zaczęły pojawiać się różne małe problemy i, chociaż drobne, konieczne było częste zmienianie dokumentacji — cztery różne zespoły, codziennie, niemal równocześnie, z dyskusjami. Wszystkie te zmiany przechodziły przez jednego inżyniera — architekta. Plik z projektem był ogromny, a w konsekwencji architekt był przytłoczony rutynową pracą związaną z dużą ilością kopiowania, edytowania, popełniał wiele błędów, musiał wszystko sprawdzać, ponownie przesyłać, a ogólnie to było bliskie chaosowi.

W tym przypadku podejście, polegające na pracy nad dokumentem MS Word, działało z dużym opóźnieniem i tworzyło problemy.

Git, Markdown

Stykając się z problemem opisanym w powyższym przykładzie, zacząłem badać tę kwestię.
Zauważyłem, że coraz popularniejsze staje się korzystanie z Markdown wraz z Gitem przy tworzeniu dokumentów.

Git to narzędzie do rozwoju. Ale czemu nie używać go do procesu dokumentowania? W tym przypadku problem wieloosobowej pracy jest rozwiązany. Ale żeby w pełni wykorzystać możliwości Gita, potrzebujemy tekstowego formatu dokumentu, musimy znaleźć inne narzędzie, które nie jest MS Word, a do tych celów świetnie nadaje się Markdown.

Markdown to prosty język znaczników tekstowych. Jest przeznaczony do tworzenia estetycznie wyglądających tekstów w zwykłych plikach formatu TXT. Jeśli tworzymy nasze dokumenty w Markdown, to połączenie Markdown — Git wydaje się naturalne.

I wszystko byłoby dobrze, i w tym miejscu można by zakończyć, gdyby nie nasz drugi warunek: "na wyjściu potrzebujemy dokumentu w określonym formacie, z atrybutami stylu korporacyjnego, stworzonego według określonego szablonu" (i zgodziliśmy się na początku, że dla pewności będzie to MS Word). To znaczy, jeśli zdecydowaliśmy się użyć Markdown, to musimy jakoś przekształcić ten plik w .docx w wymaganym formacie.

Istnieją programy do konwersji między różnymi formatami, na przykład, Pandoc.
Możesz przekonwertować plik Markdown na format .docx za pomocą tego programu.
Jednak należy pamiętać, że po pierwsze, nie wszystko, co znajduje się w Markdown, zostanie przekonwertowane na MS Word, a po drugie, MS Word to cały kraj w porównaniu z prostym, ale mimo wszystko miasteczkiem, jakim jest Markdown. Istnieje ogromna liczba rzeczy, które są w Wordzie i w żadnej formie nie ma ich w Markdown. Nie można po prostu wziąć i z określonymi kluczami Pandoc przekonwertować formatu Markdown na pożądany wygląd MS Word. Zazwyczaj więc, po konwersji, trzeba ręcznie "poprawić" otrzymany dokument .docx, co również może być czasochłonne i prowadzić do błędów.

Gdybyśmy mogli napisać skrypt, który automatycznie "wykańczałby" to, z czym nie poradził sobie Pandoc — to byłoby idealne rozwiązanie.

Ze względu na niejednorodność funkcjonalności MS Word i Markdown w ogólnym zarysie, myślę, że rozwiązanie tego problemu jest niemożliwe, ale czy można to zrobić w odniesieniu do konkretnych sytuacji, konkretnych wymagań? Moje doświadczenie pokazuje, że tak, można to zrobić i najprawdopodobniej jest to możliwe w wielu, a może nawet w większości sytuacji.

Rozwiązanie konkretnego problemu

Tak więc, w moim przypadku, po konwersji pliku za pomocą Pandoc, musiałem ręcznie przeprowadzić dodatkową obróbkę plików, a mianowicie

• dodawać w Wordzie pola z automatycznym numerowaniem nagłówków (caption) tabel i obrazków
• zmieniać styl dla tabel

Nie znalazłem, jak to zrobić standardowymi (Pandoc) lub znanymi środkami. Dlatego zastosowałem skrypt pythona z pywin32 pakietem. W rezultacie uzyskałem pełną automatyzację. Teraz mogę przekonwertować mój plik Markdown na potrzebny format dokumentu MS Word jednym poleceniem.

Zobacz szczegóły tutaj.

Uwagi

W tym przykładzie oczywiście przekształcam pewien abstrakcyjny plik Markdown, ale dokładnie ta sama metoda została zastosowana do "bojowego" dokumentu, a w wyniku otrzymałem praktycznie identyczny dokument MS Word, który wcześniej uzyskiwaliśmy przy manualnym formatowaniu.

Ogólnie, z pywin32 zyskujemy niemal pełną kontrolę nad dokumentem MS Word, co pozwala na jego edytowanie i dostosowywanie do wymogów waszych standardów korporacyjnych. Oczywiście te same cele można osiągnąć przy użyciu innych narzędzi, takich jak makra VBA, ale było mi łatwiej korzystać z Pythona.

Krótka formuła tego podejścia:

Markdown + Git -- (coś) --> MS Word

Nie jest tak ważne, czym jest „coś”. W moim przypadku był to Pandoc i Python z pywin32. Być może masz inne preferencje, ale ważne jest, że to jest możliwe. I to jest główny przekaz tego artykułu.

Podsumowując, idea polega na tym, że przy takim podejściu pracujesz tylko z plikiem Markdown i korzystasz z Git do organizowania współpracy oraz kontroli wersji, a tylko w razie potrzeby (na przykład w celu przekazania dokumentacji klientowi) automatycznie tworzysz plik w odpowiednim formacie (na przykład MS Word).

Proces

Myślę, że dla wielu ta formuła jest wystarczająca, aby zrozumieć, jak teraz może być zorganizowany proces pracy z dokumentacją. Niemniej jednak zazwyczaj nawiguję w kierunku inżynierów sieciowych, więc w ogólnych zarysach pokażę, jak teraz może wyglądać proces pracy i jak różni się to od podejścia do edytowania plików MS Word.

Dla pewności, jako platformę do pracy z Git wybierzemy GitHub. Wtedy musisz stworzyć repozytorium i umieścić plik lub pliki Markdown w gałęzi master, z którymi planujesz pracować.

Rozważymy prosty proces oparty na „github flow”. Jego opis można znaleźć zarówno w Internecie, jak i na Habrze.

Załóżmy, że nad dokumentacją pracuje cztery osoby i ty jesteś jedną z nich. Wtedy tworzone są cztery dodatkowe gałęzie (branch), na przykład z imionami tych osób. Każdy pracuje lokalnie, w swojej gałęzi, i dokonuje zmian ze wszystkimi niezbędnymi komendami git.

Wykonując jakiś zakończony fragment pracy, tworzysz pull request, inicjując w ten sposób dyskusję nad swoimi zmianami. Możliwe, że w trakcie dyskusji wyjdzie na jaw, że musisz dodać lub zmienić coś jeszcze. W takim przypadku wprowadzasz niezbędne zmiany i tworzysz dodatkowy pull request. Ostatecznie twoje zmiany zostają zaakceptowane i scalone (merge) z gałęzią master (lub odrzucone).

Oczywiście, to dość ogólny opis. Proponuję skontaktować się z waszymi deweloperami lub znaleźć kompetentne osoby, aby stworzyć szczegółowy proces. Ale chcę zauważyć, że próg wejścia do Gita jest dość niski. To nie oznacza, że protokół jest prosty, ale możesz zacząć od podstaw. Jeśli zupełnie nic nie wiesz, myślę, że poświęcając kilka godzin lub może dni na naukę i konfigurację, możesz zacząć go używać.

Jaka jest korzyść z tego podejścia w porównaniu, na przykład, do procesu opisanego w powyższym przykładzie?

W rzeczywistości procesy są dość podobne, po prostu zastąpiłeś

kopiowanie pliku -> tworzenie gałęzi (branch)
kopiowanie tekstu do końcowego pliku -> scalanie (merge)
kopiowanie ostatnich zmian do siebie -> git pull/fetch
dyskusja w korespondencji -> pull requests
tryb śledzenia -> git diff
ostatnia zatwierdzona wersja -> gałąź master
kopiowanie na zdalny serwer -> git push
…

W ten sposób zautomatyzowałeś wszystko, co musiałeś robić ręcznie.

Na wyższym poziomie pozwala ci to

• stworzyć jasny, prosty i kontrolowany proces zmian w dokumentacji
• ponieważ końcowy dokument (w naszym przykładzie MS Word) tworzysz automatycznie, co zmniejsza prawdopodobieństwo błędów związanych z formatowaniem

Uwagi

W związku z powyższym, myślę, że oczywiste jest, że nawet jeśli pracujesz nad dokumentacją sam, to korzystanie z Gita może znacznie ułatwić twoją pracę.

Wszystko to podnosi jakość dokumentacji i skraca czas jej tworzenia. I jeszcze mały bonus — nauczysz się Gita, co pomoże ci w automatyzacji twojej sieci 🙂

Jak przejść na nowy proces?

Na początku artykułu napisałem, że już jutro możesz zacząć pracować w nowy sposób. Jak przekonwertować swoją pracę na nowy tor?

Oto sekwencja kroków, które prawdopodobnie będziesz musiał wykonać:

• jeśli twój dokument jest bardzo duży, podziel go na części
• przekształć każdą część do Markdown (na przykład za pomocą Pandoc)
• zainstaluj jeden z edytorów Markdown (używam Typora)
• prawdopodobnie będziesz musiał poprawić formatowanie utworzonych dokumentów Markdown
• zacznij stosować proces opisany w poprzednim rozdziale
• jednocześnie zacznij modyfikować skrypt konwersji pod swoje zadanie (lub stwórz coś swojego)

Nie musisz czekać, aż stworzysz i doskonale poprawisz mechanizm konwersji Markdown -> wymagany na wyjściu format dokumentu. Chodzi o to, że nawet jeśli nie uda ci się szybko w pełni zautomatyzować procedury przekształcania twoich plików Markdown, i tak będziesz mógł to zrobić w pewnej formie za pomocą Pandoc, a następnie doprowadzić do ostatecznej formy ręcznie. Zwykle nie musisz tego często robić, a tylko na końcu niektórych etapów, i ta praca ręczna, chociaż niewygodna, jest moim zdaniem do zaakceptowania na etapie debugowania i nie powinna znacznie „spowalniać” procesu.

Wszystko inne (Markdown, Git, Pandoc, Typora) jest już gotowe i nie wymaga szczególnych wysiłków ani czasu, aby zacząć z nimi pracować.

Źródło: habr.com