Przegląd narzędzi do tworzenia dokumentacji strony na Drupalu

Freelancer czy zakontraktowany programista - wszyscy borykamy się z tym samym problemem, kiedy rozpoczynamy pracę nad istniejącym projektem dla klienta, jak szybko i (w miarę możliwości) bezboleśnie wdrożyć się w zastaną strukturę i kod. Zapewne każdy z nas chociaż raz w swojej karierze zapytał z nadzieją w głosie: Czy mamy tu jakąś dokumentację?

Jeśli nie potrafisz wyjaśnić czegoś w prosty sposób, to nie rozumiesz tego wystarczająco dobrze. (Albert Einstein)

Myślenie przyszłościowe

Dokumentacja jest częścią produktu, jego nieocenionym uzupełnieniem i drogowskazem, zarówno dla programisty, menadżera, product ownera, jak i końcowego odbiorcy. Dobrze skonstruowana i napisana dokumentacja to obopólna korzyść. Z jednej strony minimalizujemy zakres problemów z jakimi będzie się do nas zwracać klient, a z drugiej - ułatwiamy start osobom, które dołączą do naszego zespołu lub przejmą od nas wsparcie systemu. Zatem posiadanie i (co szczególnie ważne) utrzymywanie jak najbardziej aktualnej dokumentacji jest inwestycją i strategicznym posunięciem, szczególnie w przypadku dużych projektów.

Jeśli coś nie jest udokumentowane, nie istnieje. (Sitepoint, A Guide to Writing Your First Software Documentation)

Dokumentacja dokumentacji nie równa

Na najwyższym poziomie uogólnienia możemy podzielić dokumentację projektu na: systemową (ang. system documentation) oraz użytkową (ang. end user documentation).

Pierwszym typem materiałów będą szczególnie zainteresowani deweloperzy, drugim najczęściej sam klient oraz odbiorca końcowy, czyli użytkownik Internetu. Jak jednak poradzić sobie z wyjaśnieniem wszystkich zawiłości i specyfiki danego projektu, jak najlepiej udokumentować procesy dziejące się na zapleczu oraz jak w obrazowy i łatwo przyswajalny sposób rozwiać wątpliwości użytkowników? Na ratunek przychodzi cała gama narzędzi, które swoimi funkcjonalnościami pomogą nam odpowiedzieć na te pytania, a także stworzyć dokumentację naszej strony.

Dokumentacja jak książka

Jedną z powszechnie używanych form gromadzenia dokumentacji jest tworzenie hierarchicznej treści z rozdziałami i podrozdziałami – zupełnie jak w książce, czyli papierowej wersji instrukcji użytkowania dołączanej do każdego produktu.

Istnieje kilka narzędzi umożliwiających tworzenie takiej struktury treści. Wszystkie posiadają wbudowane edytory tekstu pozwalające w prosty sposób dodawać fragmentu kodu, listy, tabele i załączniki typu media.

Confluence

Confluence jest jednym z bardziej przyjemnych i rozbudowanych narzędzi firmy Atlassian. Sami twórcy określają je jako przyjazne miejsce, gdzie spotykają się wiedza i współpraca. Codzienna praca z tym narzędziem pokazuje, że tak właśnie jest. Przyzwyczailiśmy się już do struktury stron typu wiki, dlatego poruszanie się oraz dodawanie treści w Confluence nie sprawia trudności nawet osobom nietechnicznym.

W kilku prostych krokach (szczególnie jeśli już korzystamy z innych produktów Atlassian) otrzymujemy spersonalizowaną stronę z możliwością tworzenia wielu przestrzeni (np. dla kilku wersji produktu), w których budowane są strony z artykułami. Do dyspozycji mamy rozbudowany samouczek oraz kilkadziesiąt szablonów treści. Tworzenie naszej “książki” ułatwia możliwość swobodnego przeciągania i decydowania o kolejności oraz umiejscowieniu dodawanych podstron, możliwość tagowania, linkowania, komentowania oraz ich oznaczania. Całość jest graficznie przejrzysta i czytelna. Co więcej, w darmowej wersji mamy do dyspozycji 2GB przestrzeni i możemy zaprosić do współpracy do 10 osób. Confluence warto wypróbować, szczególnie jeśli nasz kod trzymamy w repozytorium na Bitbucket, a zadania rozdzielamy przy użyciu Jira Software.

GitHub Pages i GitLab Wiki

Jeśli lubisz trzymać dokumentację blisko swojego kodu, idealnym rozwiązaniem są oferowane przez hostingowe serwisy internetowe funkcje wiki stworzone właśnie w tym celu. Nie mamy co prawda do dyspozycji szablonów artykułów, jednak wprowadzane treści są zawsze pod ręką, zaraz obok repozytorium, zadań czy procesów wdrażania nowego kodu. Organizacja treści jest zbliżona do wspomnianego wcześniej Confluence. Gitlab umożliwia nawet import istniejącej dokumentacji właśnie z tego narzędzia. Poszczególne artykuły możemy grupować poprzez wskazanie ścieżki w wirtualnym drzewie naszych rozdziałów. Podczas dodawania treści mamy do dyspozycji prosty edytor, który wspiera takie formaty jak Markdown, Rdoc, AsciiDoc, reStructuredText czy Org, a sama publikacja odbywa się na zasadzie dodawania kolejnej paczki kodu (commit message). Github Pages posiada także domyślne skórki, które sprawią, że strona naszej dokumentacji będzie wyglądała profesjonalnie.

Camunda Modeler i Process Street

Jeśli moduł Workflows jest centrum, wokół którego obraca się funkcjonowanie całej strony, to z pewnością dla zrozumienia wszystkich zależności i procesów dziejących się na stronie (np. jak przebiega proces brania pożyczki, ubiegania się o dofinansowanie, rezerwacji wizyty itp.) nieocenioną pomocą okażą się takie narzędzia jak Camunda Modeler czy Process Street. Są one przydatne zarówno w planowaniu procesów, jak i ich dokumentowaniu. Głównym celem tych narzędzi jest wspieranie zarządzania procesami biznesowymi (Business Process Management, BPM) oraz (w przypadku Camundy) tworzenia drzew decyzyjnych (Decision Model and Notation, DMN).

W skrócie, jeśli istnieją jakieś powtarzające się procesy na naszej stronie, które warto udokumentować, możemy to zrobić za pomocą tych narzędzi. W kilka sekund będziemy w stanie stworzyć dokumenty zawierające procedury czy uruchomić procesy dla swoich współpracowników. Process Street wykorzystywany jest przy wdrożeniach nowych rozwiązań lub publikowaniu nowych wersji systemu.

O ile zarząd będzie zachwycony możliwościami Process Street, programiści i analitycy biznesowi chętniej skorzystają z Camunda Modeller. Program działa pod wszystkimi systemami operacyjnymi oraz funkcjonuje jako chmura. Pozwala on na wierne odzwierciedlenie wszelkich procesów i połączeń między serwerami. Jest tam również specjalne miejsce przeznaczone na gromadzenie wszystkich niezbędnych informacji, jakich może potrzebować deweloper: adresy serwerów, format wysyłanych zapytań oraz otrzymywanych odpowiedzi wraz z parametrami itp. Całość jest niezwykle przejrzysta i intuicyjna w użytkowaniu.

Dokumentacja jak kod

Pora przejść do rozwiązań, które są miodem na serce najbardziej zagorzałych programistów – dokumentacja w kodzie! Z perspektywy nowego członka zespołu w dużym projekcie dla klienta, dokumentacja będąca częścią kodu jest idealnym rozwiązaniem. Kultura dokumentacji technicznej w dzisiejszym rozumieniu została zapoczątkowana w 2014 roku przez pracowników Twittera, którzy od powszechnie przyjętego wzorca – deweloper pisze kod, niech pisze również dokumentację – poszli o krok dalej i stwierdzili, żeby pisał ją jak kod. Docs as code przerósł najśmielsze oczekiwania. Mówimy tutaj o pisaniu dokumentacji w tym samym miejscu co kod, posługując się dokładnie tym samym procesem publikowania, jak podczas dodawania kodu – commit, pull request, build. Temu podejściu sprzyjały stosowane już wcześniej komentarze w kodzie.

PrzeczytajMnie.md!

Każdy z pewnością spotkał się z plikiem o nazwie README.md. Być może był on zwykłym plikiem tekstowym lub w jednym z tzw. lekkich formatów (ang. lightweight text formats). Zawiera podstawowe informacje na temat projektu: jak postawić jego wersję deweloperską lokalnie, kto go stworzył i utrzymuje itp.

Można jednak pójść o krok dalej i w ten sposób stworzyć całą dokumentację projektu. Do tego jednak warto użyć jednego z dostępnych formatów, który za nas przekształca uproszczoną wersję tekstu na tekst sformatowany i łatwy do czytania dla użytkownika. Jednymi z najbardziej powszechnie używanych formatów są Markdown oraz reStructuredText.

Wybuduj swoją dokumentację

A gdyby tak można zautomatyzować cały proces na podstawie komentarzy do istniejącego kodu i przy tym stworzyć coś w rodzaju dokumentacji-książki, która będzie się aktualizować z każdą naszą zmianą w kodzie? Oczywiście nic nie jest w stanie zastąpić wkładu człowieka w tworzenie dokumentacji, ale posiadanie szkieletu, głównego jej zarysu w sposób automatyczny brzmi zachęcająco.

Istnieje wiele taki generatorów, z których najbardziej przydatne dla drupalowców będą oczywiście te bazujące na kodzie PHP. Wśród nich godne polecenia są:

• ApiGen – tworzy czystą dokumentację API na bardzie kodu źródłowego w PHP.
• Dexy – jeden z bardziej wszechstronnych generatorów, obsługuje kilka języków programowania oraz formatów wejściowych i wyjściowych.
• docgenerator – pozwala na organizację dokumentacji w formie plików Markdown.
• DocumentUp – dla posiadaczy kodu na GitHub, pozwala upiększyć dokumentację stworzoną przy użyciu formatu Markdown.
• Doxygen – wspiera wiele języków programowania, generuje dokumentację online (HTML) lub jako podręcznik w formacie LateX lub innych tekstowych (PDF, MS Word).
• phpDocumentor – jeden z pierwszych tego typu, pozwala tworzyć diagramy klas w UML, wspiera najnowszą wersję PHP, szeroki zakres pomocy, wiele lat doświadczenia.
• PhpDox – nie ogranicza się jedynie do dokumentacji API, zebrane informacje przechowywane są w plikach XML, które można dowolnie modyfikować a następnie generować do HTML.

Użyj Drupala

W naszej agencji drupalowej postanowiliśmy wykorzystać Drupala do stworzenia dokumentacji na wewnętrzne potrzeby firmy. Podstawowa wersja strony drupalowej jest łatwa w przygotowaniu i posiada domyślne typy zawartości, które na początek w zupełności wystarczą. Dodatkowo, nie trzeba się niczego nowego uczyć – przecież jesteśmy specjalistami od Drupala! W naszym przypadku włączyliśmy dodatkowo moduł “Book”, aby dodawane strony tworzyły kolekcje powiązane ze sobą, zupełnie jak w przypadku książki.

Główny widok dokumentacji składa się z dwóch części: po lewej stronie znajduje się blok z drzewem zawartości, a po prawej ładowana jest treść wybranego rozdziału. Każda strona dodawana jest jako osobny node, do tworzenia/edycji zawartości korzystamy z domyślnego CKEditora. Jest on wzbogacony o dodatkową wtyczkę CodeSnippet. Ubraliśmy wszystko w nasze firmowe barwy i… voilà! Treści są moderowane zarówno przez deweloperów, jak i osoby nietechniczne. Trzymane są tam treści od typowo HR-owych po lokalne stawianie projektów. Nasi nowi pracownicy otrzymują gotową skarbnicę wiedzy, jak się poruszać po wszystkich firmowych zagadnieniach oraz jak rozpocząć pracę na przydzielonym projekcie.

Podsumowanie

Narzędzi pomagających w tworzeniu, i co ważniejsze, utrzymywaniu aktualnej dokumentacji jest wiele. To, które z nich wybierzemy zależy od specyfiki naszego projektu: jego wielkości, liczby i rodzaju zastosowanych modułów. Wpływ ma również to, czy strona w głównej mierze jest statyczna, czy opiera się na procesach, kto będzie tworzył oraz używał dokumentacji, czy chcemy ją udostępniać i wiele, wiele innych. Niezmiennym jednak pozostanie fakt, że dokumentacja jest częścią produktu i posiada walor ekonomiczny, ponieważ pozwala redukować koszty (godziny spędzone przez dewelopera na wdrażaniu się). Dobra dokumentacja pomaga również przyciągać klientów (jak już cytowaliśmy, jeśli coś nie ma dokumentacji, nie istnieje ;)) Zatem do dzieła!