AsciiDoctor – dokumentacja techniczna „na poważnie”

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.

CechaPliki WordGoogle DocsConfluence WikiAsciiDoctor
Miejsce przechowywaniaWspółdzielony katalog lub binarna wersja w repozytoriumChmura Google WikiTekstowa wersja w repozytorium
Sprawdzanie różnic pomiędzy wersjamiRęczny lub dodatkowe zewnętrzne narzędziaTak (wbudowane)Tak (wbudowane)Tak (git diff)
Możliwość dołączania opisu poszczególnych wersjiNieTak (przez komentarz do taga)Tak (wbudowane)Tak (git commit -m '…’)
Sprawdzanie autorstwa poszczególnych fragmentówNieNieNieTak (git annotate)
Proces „doc review”NieNieNieTak (Gerrit, Bitbucket, Github, itp.)
Możliwość dodawania komentarzy przez redaktorówTakTakNieNie (tylko jako zakomentowane treści w pliku źródłowym)
Praca bezpośrednio ze sformatowanym tekstem (WYSIWYG)TakTakTak / nie (edytor zaawansowany)Nie (podgląd „live” wymaga dodatkowego programu lub wtyczki)
Łatwość utworzenia pierwszego dokumentuTakTakTakNie (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)TakTak
System uprawnień do przeglądania i edycjiNieTakTakEdycja: 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 dokumentamiNieTak (jako zwykłe linki)TakTak
Jakość dokumentu PDFPrzyzwoitaPrzyzwoitaŚredniaWysoka
Możliwość tworzenia szablonów powtarzanych fragmentówNieNieTakTak
Formatowanie kodu źródłowegoNieNieTakTak
Objaśnienia do kodu źródłowegoNieNieNieTak
Możliwość używania zmiennych i podstawieńNieNieNieTak
Szablony typowych bloków: wskazówka, uwaga, ostrzeżenie, itp.NieNieTakTak
Możliwość przetrzymywana osobnych wersji dokumentacji dla różnych gałęzi koduNieNieNieTak
Próg wejścia dla nietechnicznych członków zespołuBrakBrakŚredniWysoki 🙁
DevOps – ready (możliwość publikacji dokumentu PDF po każdej zmianie)NieNieNieTak
Porównanie narzędzi do tworzenia dokumentacji

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:

Formatowanie tekstu z użyciem AsciiDoctor
Formatowanie tekstu z użyciem AsciiDoctor

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)

Konfiguracja plugina Gradle dla AsciiDoctor
Konfiguracja plugina Gradle dla AsciiDoctor

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.

Wygenerowany dokument HTML
Wygenerowany dokument HTML
Wygenerowany dokument PDF
Wygenerowany dokument 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:

Przykład pracy z AsciiDoc z użyciem plugina do IntelliJ Idea.
Przykład pracy z AsciiDoc z użyciem plugina do IntelliJ Idea – po lewej stronie kod, po prawej podgląd

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:

AsciiDoc - przykład formatowania kodu źródłowego
AsciiDoc – przykład formatowania kodu źródłowego

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:

AsciiDoctor - przykład kotwicy do rozdziału.
AsciiDoctor – przykład kotwicy do rozdziału.

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.

O autorze

Marek Berkan Marek Berkan: programista, entuzjasta tworzenia oprogramowania, zarządzania zespołami technicznymi. Prywatnie motocyklista, kolarz MTB, biegacz, żeglarz, rekreacyjny wspinacz, zamiłowany turysta. Witryny: , , .

2 komentarze do “AsciiDoctor – dokumentacja techniczna „na poważnie”

  1. Jachu

    Podobnie można też dokumentować w plikach md.
    Spodziewam się że asciidoc ma więcej możliwości, ale nie wszyscy ich potrzebują.

    Odpowiedz

Skomentuj Jachu Anuluj pisanie odpowiedzi

Twój adres e-mail nie zostanie opublikowany. Wymagane pola są oznaczone *