11.01.20184 min
Ringier Axel Springer Tech

DreamLabRingier Axel Springer Tech

Pisz dokumentację tak jak kod

Dzięki podejściu Docs as Code zmniejszamy context-switching w czasie pisania, ale przede wszystkim zaczynamy traktować dokumentację jak ważną część produktu.

Pisz dokumentację tak jak kod

Wśród zespołów tworzących oprogramowanie w organizacjach IT najczęściej napotykam następującą hierarchię wartości: Kod > Testy > Dokumentacja. Generalnie uważam to podejście za słuszne, co może dziwnie brzmieć z punktu widzenia osoby, dla której pisanie dokumentacji jest bardzo ważne. Ale przecież bez kodu nie byłoby ani testów, ani właśnie dokumentacji. Ich samodzielne funkcjonowanie, jako osobnych tworów, nie jest zasadne.

Wydaje mi się jednak, że ta hierarchia wynika również z innych powodów. O ile sporo mówi się o najlepszych praktykach przy pisaniu kodu i testowaniu, to często umyka nam proces tworzenia dokumentacji. Czy da się zatem pisać ją prościej, skoro podobno dobry proces to prosty proces?

Kultura dokumentacji

2014

Na scenę konferencji Write The Docs wychodzi dwóch pracowników Twittera, żeby opowiedzieć jak pracują nad “kulturą dokumentacji” w swojej firmie. Mówią o tym, że jest problem z doborem narzędzi - każdy używa tego co mu pasuje, nie wszystkie treści są aktualne, trudno cokolwiek znaleźć. Wspominają, że nie stać ich na zatrudnienie wielu techwriterów, którzy byliby za to wszystko odpowiedzialni.

Zrozumieli więc, że muszą zmienić podejście do pisania dokumentacji. Do popularnego w naszym środowisku zdania: “Skoro developerzy piszą kod, to niech piszą dokumentację.”, oni dodali jeszcze drugie: “Skoro piszą dokumentację, to niech piszą ją jak kod”.

2015

Na scenę tej samej konferencji wychodzi techwriterka Google’a. Mówi, że postanowili zaryzykować, bo potrzebowali usprawnić wewnętrzną dokumentację swoich narzędzi. Zrobili więc to, o czym Twitter opowiadał rok temu. Efekt? W ciągu ośmiu miesięcy w ich nowym narzędziu powstała dokumentacja ponad 1600 projektów. Wzrost wykładniczy, bez żadnego wewnętrznego marketingu, tylko promocja word-of-mouth wśród programistów.

To (re)ewolucja!

Co to za cudowne podejście?

Piszemy dokumentację tak jak kod. Dosłownie.

W formacie tekstowym, w tym samym miejscu co kod (np. git), stosując podobne praktyki: pull requests, code review. Nawet ją “buildujemy” jak kod, generując strony w HTMLu i testujemy, sprawdzając czy wszystkie obrazy się w niej ładują. Docs as code to nic nadzwyczajnego. Zdecydowanie nie jest to rewolucja, ale nie chodzi tylko o prosty reference manual, generowany z komentarzy w kodzie. Chodzi o pełną dokumentację: tutoriale, how-to’s, FAQ, słowniki, changelogi i inne.

Skoro to nie przełom, to skąd się wzięło to podejście? Trzymanie dokumentacji w komentarzach w kodzie zdecydowanie mu pomogło, podobnie rozpowszechnione używanie tzw. lightweight text formats, jak Markdown oraz generatorów stron do nich (np. Jekyll). Niemałą rolę odegrał cały ruch OpenSource, który nauczył nas, że jeśli coś nie ma dokumentacji, to lepiej tego nie używać. Swój wkład ma też na pewno community Pythonowe, tworząc jedno z lepszych narzędzi do dokumentacji, oraz inicjatywa Read The Docs, która z niego korzysta.

Wymienić można by pewnie jeszcze sporo rzeczy. Trzeba jednak na koniec tej wyliczanki wspomnieć o Twitterze, bo to oni dokonali syntezy narzędzi i podejścia developerskiego do tematu. Swoją prezentacją pokazali, że dobra dokumentacja, to nie tylko domena projektów OS, ale też poważnych firm technologicznych.

Jak zacząć? Od użytkownika

Co zyskujemy stosując podejście docs as code? Oczywiście, zmniejszamy context-switching w czasie pisania dokumentacji. Wszystko można pisać w swoim edytorze, bez wchodzenia do innych narzędzi. Ale to nie wszystko. Pisząc dokumentację tak jak kod, podświadomie zaczynamy traktować ją jak kod. Jako coś ważnego w produkcie. Coś, na czym mocno zależy użytkownikowi i co trzeba zrobić dobrze.

Ale zanim zaczniesz pisać dokumentację w Markdownie w podfolderze docs, koło swojego src, pamiętaj o jednym. Dokumentacja nieczytana jest gorsza niż brak dokumentacji. Jest czystą stratą czasu i pieniędzy. Zapytaj swoich użytkowników czego potrzebują, z czym sobie nie radzą. Jakimi dokumentami możesz ich wesprzeć, żeby mogli używać twojego produktu bezproblemowo.

Prosto nie znaczy łatwo

Jak powiedział podobno znany muzyk jazzowy - “Simple ain’t easy”. Tak samo jest w tym przypadku. Całe podejście może się wydawać proste, ale łatwe nie jest. Tak jak pokazał Twitter czy Google, nie chodzi tylko o zmianę narzędzi, ale też o przebudowę kultury pisania dokumentacji w organizacji. W DreamLabie jesteśmy na początku tej drogi i widzimy wiele wyzwań z nią związanych. Ale widzimy też, że warto nią podążać.

2017

Przeglądam w pracy oficjalną dokumentację chatu Microsoft Teams. Po chwili rzuca mi się w oczy przycisk Edit. Przechodzę na Githuba, do publicznego repozytorium, pełnego dokumentów w markdownie. Uśmiech nie schodzi mi z twarzy. 

Linki dla zainteresowanych

Autor: Witek Socha, w tej chwili zajmuje się dokumentacją (i nie tylko) w DreamLabie. Wcześniej zarządzał community w Estimote oraz pracował jako programista i Scrum Master w Picodi. Bardzo ceni feedback, więc napisz, co myślisz.

<p>Loading...</p>