W niemal każdym projekcie innym niż PoC (Proof of Concept) trzeba napisać dokumentację. Mimo że często bagatelizowany, jest to element oprogramowania, który świadczy o profesjonalizmie zespołu, w szczególności w oczach kolejnych członków zespołu, którzy dołączają później do projektu i chcą szybko się w niego wdrożyć. W czasie swojej pracy zauważyłem niestety nieprzyjemną prawidłowość: większość osób przychodzących do projektu oczekuje dobrej dokumentacji, ale później poproszeni o minimalne udokumentowanie czegokolwiek co zrobili zaskakująco nie mają czasu albo chęci :-(.
Z jakością dokumentacji jest jak z czystym kodem: trzeba o niego dbać: usuwać nieaktualne lub nadmiarowe fragmenty, aktualizować o wprowadzone zmiany, uzupełniać odnośniki, uspójniać wzorce, itp. O większych zmianach w dokumentacji można myśleć jak o refaktoringach kodu.
Różnica przy pracy z dokumentacją vs. z kodem aplikacji jest taka, że kompilator sprawdzi czy kod się kompiluje, tester sprawdzi czy kod aplikacji działa, testy jednostkowe lub automatyczne sprawdzą czy nie ma regresji. Ponadto w ramach procesu przeglądu kod źródłowy przed wypchnięciem commita do repo zostanie przejrzany przez kolegę/koleżankę z zespołu, więc czytelność i jakość jest większa, bo zaangażowane osoby (autor i reviewer) nie chcą żeby „był wstyd”. Z kolei przy pisaniu dokumentacji jest przeświadczenie że „Word przyjmie wszystko” – w pierwszej wersji dokumentu dba się o jakość, ale często przy kolejnych zmianach już jest z tym coraz trudniej.
Tworzenie dokumentacji jak tworzenie oprogramowania
Kończąc przydługi wstęp filozoficzny, teza którą wstawiam w tym wpisie jest taka, że w dobrym zespole każdy dokument żyjący dłużej niż „do jednego pokazania klientowi” powinien być traktowany jak element oprogramowania i niemal jak kod aplikacji:
- przetrzymywany w repozytorium
- podlegający procesowi „doc review” – analogicznie i z użyciem tych samych narzędzi co „code review”
- unikający duplikacji z wykorzystaniem elementów wspólnych
Najczęściej wykorzystywane narzędzia do tworzenia dokumentacji, jak dokument Word dokument Google Doc czy dokument na Wiki słabo lub w ogóle nie nadają się do tego celu, co staram się uzasadnić w poniższej tabeli. Rozwiązaniem jest dokument w formacie tekstowym, który można łatwo umieścić w repozytorium, a dodatkowym narzędziem utworzyć z niego docelowy dokument PDF, który można przesłać klientowi lub umieścić w ogólnodostępnym miejscu dla zespołu. Takim rozwiązaniem jest AsciiDoctor (https://asciidoctor.org/) opisany niżej.
Porównanie tradycyjnych i tekstowych narzędzi do tworzenia dokumentacji
Moje subiektywne porównanie popularnych narzędzi do tworzenia dokumentacji. Z góry zaznaczam że nie mam żądnego zaawansowanego doświadczenia z dokumentacji Word ani chmurą Microsoft, więc może tam są narzędzia do porównywania i pracy grupowe. W poniższym zestawieniu zakładam, że chodzi o „surowe” pliki Word otwierane przy pomocy LibreOffice.
Cecha | Pliki Word | Google Docs | Confluence Wiki | AsciiDoctor |
---|---|---|---|---|
Miejsce przechowywania | Współdzielony katalog lub binarna wersja w repozytorium | Chmura Google | Wiki | Tekstowa wersja w repozytorium |
Sprawdzanie różnic pomiędzy wersjami | Ręczny lub dodatkowe zewnętrzne narzędzia | Tak (wbudowane) | Tak (wbudowane) | Tak (git diff) |
Możliwość dołączania opisu poszczególnych wersji | Nie | Tak (przez komentarz do taga) | Tak (wbudowane) | Tak (git commit -m '…’) |
Sprawdzanie autorstwa poszczególnych fragmentów | Nie | Nie | Nie | Tak (git annotate) |
Proces „doc review” | Nie | Nie | Nie | Tak (Gerrit, Bitbucket, Github, itp.) |
Możliwość dodawania komentarzy przez redaktorów | Tak | Tak | Nie | Nie (tylko jako zakomentowane treści w pliku źródłowym) |
Praca bezpośrednio ze sformatowanym tekstem (WYSIWYG) | Tak | Tak | Tak / nie (edytor zaawansowany) | Nie (podgląd „live” wymaga dodatkowego programu lub wtyczki) |
Łatwość utworzenia pierwszego dokumentu | Tak | Tak | Tak | Nie (wymaga konfiguracji projektu i narzędzi) |
Łatwość utrzymania struktury dokumentów | Średnio (wymaga utrzymania struktury katalogów i pilnowania nazw plików) | Średnio (wymaga utrzymania struktury katalogów i pilnowania nazw plików) | Tak | Tak |
System uprawnień do przeglądania i edycji | Nie | Tak | Tak | Edycja: Tak (tak jak w repozytorium kodu) Przeglądanie: Nie (potrzebny osobny system uprawnień do opublikowanych dokumentów) |
Możliwość tworzenia odnośników pomiędzy rozdziałami i dokumentami | Nie | Tak (jako zwykłe linki) | Tak | Tak |
Jakość dokumentu PDF | Przyzwoita | Przyzwoita | Średnia | Wysoka |
Możliwość tworzenia szablonów powtarzanych fragmentów | Nie | Nie | Tak | Tak |
Formatowanie kodu źródłowego | Nie | Nie | Tak | Tak |
Objaśnienia do kodu źródłowego | Nie | Nie | Nie | Tak |
Możliwość używania zmiennych i podstawień | Nie | Nie | Nie | Tak |
Szablony typowych bloków: wskazówka, uwaga, ostrzeżenie, itp. | Nie | Nie | Tak | Tak |
Możliwość przetrzymywana osobnych wersji dokumentacji dla różnych gałęzi kodu | Nie | Nie | Nie | Tak |
Próg wejścia dla nietechnicznych członków zespołu | Brak | Brak | Średni | Wysoki 🙁 |
DevOps – ready (możliwość publikacji dokumentu PDF po każdej zmianie) | Nie | Nie | Nie | Tak |
Jeżeli powyższe cechy były niejasne, to zaraz zostaną wytłumaczone na podstawie narzędzia AsciiDoctor.
AsciiDoctor – generowanie plików PDF i HTML z formatu tekstowego
Zasada pracy z AsciiDoctor (https://asciidoctor.org/) jest prosta: treść dokumentu jest przetrzymywana w formacie tekstowym, a przy pomocy tego narzędzia jest generowana docelowa postać dokumentacji w formacie HTML (do publikacji w wewnętrznym intranecie lub w internecie) i PDF (np. do wysłania klientowi lub wydruku).
Postać tekstowa jest sformatowana z użyciem składni, której trzeba się nauczyć – to pierwszy próg wejścia:
Drugim wyzwaniem jest konieczność lokalnego zainstalowana programu AsciiDoctor służącego do generowania docelowej dokumentacji. Ale, aby tego uniknąć, można zastosować plugin do Gradle (jednego z popularnych narzędzi służących do budowania artefaktów aplikacji, podobnego do Maven)
Gotowy przykład takiej konfiguracji można pobrać z repozytorium https://github.com/mberkan/asciidoctor-example.
Utworzenie dokumentu w zależności od oczekiwanego formatu wykonuje się poleceniem:
./gradlew asciidoctor # Generuje HTML
./gradlew asciidoctorPdf # Generuje PDF
Wygenerowane dokumenty znajdują się odpowiednio w pliku build/html5/example-document-pl.html
lub ./build/pdf/example-document-pl.pdf
.
Przykładowy wygenerowany plik można pobrać także bezpośrednio tu: example-document-pl.pdf.
Praca w trybie WYSIWYG
Format AsciiDoctor z definicji jest trybem tekstowym, więc edytując plik nie widzimy jak docelowo będzie wyglądać dokumentacja. Jednakże przy pomocy dodatkowych programów, jak plugin AsciiDoc do IntelliJ Idea, możemy na żywo podglądać jak będzie wyglądać dokument, oczywiście z wyjątkiem parametrów, które są „obliczane” w momencie generacji:
Warte odnotowania jest, że zarówno sam AsciiDoctor, opisywany plugin jak i IntelliJ Idea są darmowe (Idea w wersji „Community”).
Możliwości formatowania
Format AsciiDoctor ma niemal wszystkie możliwości formatowania wystarczające do tworzenia eleganckich dokumentów technicznych (szczegółowy opis: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/). Jednak „killer-ficzerem” w stosunku do porównywanych formatów Word, Google Docs lub Confluence Wiki jest automatyczne formatowanie przykładów kodu źródłowego z kolorowaniem składni i możliwością umieszczenia komentarzy:
Możliwość tworzenia „ładnych kotwic”
W czasie pracy w zespole często pojawia się sugestia „sprawdź w dokumentacji”, w szczególności w przypadku powtarzających się uwag w ramach przeglądu kodu. Z użyciem AsciiDoc można do rozdziałów, akapitów, a nawet pozycji list tworzyć „kotwice”, które następnie mogę być częścią odnośnika HTML #nazwa-kotwicy. Do takich miejsc można się odnosić zarówno z wnętrza dokumentu (aby czytelnik mógł po nim nawigować) ale także z zewnątrz w postaci adresu bezwzględnego:
Koszt migracji
Niniejszy artykuł powstał jako podsumowanie migracji z Google Docs dużego dokumentu technicznego (131 stron) z zaawansowanym formatowaniem – przetworzenie go na AsciiDoc i dogranie formatowania zajęło mi 10,5h. To sporo, ale ze względu na fakt, że dokument jest stale rozwijany i „koszt ludzki” jego utrzymania w Google Docs był spory (począwszy od „rozjeżdżającego się” spisu treści), sądzę że to była świetna inwestycja. Prawdopodobnie przy konieczności migracji większej liczny dokumentów można by rozważyć jakieś półautomatyczne usprawnienia.
Trudność utworzenia pierwszego dokumentu i wysoki próg wejścia dla nietechnicznych członków zespołu
Gdyby nie trudność tworzenia pierwszego dokumentu (konfiguracja budowania) oraz próg wejścia dla nietechnicznych członków zespołu, można by powiedzieć że AsciiDoctor jest formatem idealnym. Niestety praktyka wskazuje, że przez brak popularyzacji takiego narzędzia (lub podobnych) często pierwszym wyborem zespołu jest rozwiązanie szybsze w uruchomieniu (Word, Google Docs, Wiki), a potem „już tak zostaje”.
Niniejszy artykuł jest formą popularyzacji AsciiDoctor :-), a przykładowa konfiguracja powinna znacząco ułatwić uruchomienie. Mam nadzieję że będzie on pomocą dla kierowników zespołów technicznych i architektów odpowiedzialnych za tworzenie i utrzymanie dokumentacji.
130 stron / 10 h to i tak nieźle 🙂
Z automatów polecam pandoc: https://docs.asciidoctor.org/asciidoctor/latest/migrate/ms-word/
To zawsze wymaga trochę zabawy z dostrojeniem, więc pierwszy dokument zajmie pare godzin (może nawet 10), ale potem to już pestka. Pierwsza wersja wyjdzie „płaska”, trzeba poczytać jak obsłużyć nagłówki, obrazki itp.
Podobnie można też dokumentować w plikach md.
Spodziewam się że asciidoc ma więcej możliwości, ale nie wszyscy ich potrzebują.