18.07.20187 min
Rafał Pawlicki
Ringier Axel Springer Tech

Rafał PawlickiSenior Developer Ringier Axel Springer Tech

Dokumentacja okiem dewelopera

O roli dokumentacji w rozwijaniu produktów i projektach informatycznych.

Dokumentacja okiem dewelopera

Rozwijanie produktów, projektów informatycznych to ciągłe dodawanie nowych funkcjonalności, poprawianie wykrytych błędów i wprowadzanie zmian tak, aby zwiększać wartość biznesową tego, co tworzymy. Proces ten zazwyczaj składa się z analizy tematu, planowania prac, realizacji, testów i wdrożenia. Czyżby?

W takim razie, gdzie w tym wszystkim jest miejsce na dokumentację? Czy jest ona częścią produktu, czy miłym - ale jednak - dodatkiem? A może warunkiem niezbędnym do wdrożenia? Kiedy powinniśmy ją pisać?

Postaram się odpowiedzieć na powyższe pytania, bazując na własnych doświadczeniach z ponad dziesięcioletniej pracy jako programista. Chciałbym przybliżyć metody tworzenia dokumentacji oraz momenty, w których jest to istotne i możliwe do realizacji. A przede wszystkim - chciałbym zainspirować Cię do rozpoczęcia rozmowy na temat dokumentacji w Twojej firmie.

Kiedy potrzebujemy dokumentacji?

Odpowiedź jest prosta - zawsze, choć oczywiście nie zawsze w takiej samej formie. Jeśli tworzymy prostą aplikację lub bibliotekę, to zazwyczaj wystarczy przygotowanie README (pliku z krótkim opisem i metodą instalacji) i kilku przykładów. Jeśli natomiast pracujemy nad bardziej złożonym projektem, powinniśmy przygotować jego pełną dokumentację - zarówno dla użytkowników, jak i na potrzeby utrzymania.

Czy oprogramowanie dostępne tylko wewnątrz firmy musi mieć dokumentację? To pytanie, z którym spotykam się często. Odpowiedź staje się oczywista, jeśli zadamy je nieco inaczej, np. „Czy chciałbyś zapoznać się dokumentacją narzędzia wewnętrznego, z którego musisz skorzystać?". Nie jest istotne, czy nasz projekt trafi do zewnętrznych klientów, czy do zespołu, który siedzi po drugiej stronie pokoju.

Generalnie, niezależnie od formy, wszyscy czasem potrzebujemy wprowadzenia do systemu, z którym mamy pracować. Nie oznacza to, że dokumentacja musi mieć 435 stron i przypisy - zazwyczaj nie musi być wcale obszerna. Richard Feynmann powiedział kiedyś:

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

Ta maksyma sprawdza się świetnie przy pisaniu dokumentacji. Powinniśmy skupiać się na tym, aby odbiorca wiedział, czym jest to, co opisujemy, jak tego użyć oraz z jakich funkcjonalności może skorzystać.

Czy dokumentacja jest częścią produktu?

To kolejne pytanie, które pojawiało się wielokrotnie w trakcie prac nad poprawieniem jakości dokumentacji. Żaden produkt nie jest aż tak prosty w obsłudze czy utrzymaniu, że nie wymaga opisu, wprowadzenia czy przykładów wykorzystania. Konsekwencją takiego optymistycznego założenia może być powtarzająca się konieczność świadczenia wsparcia i odpowiadania na pytania użytkowników. Są to koszty, które można znacznie ograniczyć, poświęcając trochę czasu na napisanie dokumentacji.

Świetnym przykładem może być IKEA, która nawet do najprostszego produktu wymagającego montażu dołącza prostą instrukcję. Produkty IKEA nie byłyby tym samym - może nawet nie sprzedawałyby się tak dobrze - gdyby nie możliwość ich samodzielnego montażu w oparciu o dokumentację.

A jeśli już planujemy sprzedawać nasz produkt jako gotowe rozwiązanie to dokumentacja jest wręcz obowiązkowa. W przypadku projektów informatycznych jest często tym, co jako pierwsze wpada w ręce potencjalnego klienta. Często na podstawie informacji w niej zawartych zapada decyzja, czy dany produkt zostanie kupiony, czy też nie.

W mniejszej skali, na poziomie pojedynczych aplikacji czy bibliotek, jest podobnie - najpierw chcemy wiedzieć czy to jest właśnie to, czego szukamy.

Jak powinniśmy pisać?

Miałem niedawno okazję uczestniczyć w konferencji soap! technical communication. Prelegenci zaprezentowali kilka koncepcji, do których chciałbym tu nawiązać, ponieważ mówią o najważniejszych według mnie aspektach tworzenia dobrej dokumentacji. Szczególne podziękowania dla Natalii Woszczek i Pawła Kowaluka za świetne prezentacje, które pozwoliły mi odpowiedzieć na pytanie zadane w tym akapicie - znajdziecie je tu i tu.

Przede wszystkim istotne jest to, kto jest naszym głównym odbiorcą. W zależności od tego powinniśmy dostosować zarówno język, jak i formę komunikacji. Inaczej będziemy komunikować się z osobą techniczną, inaczej z kimś, kto zajmuje się biznesem. Podamy inne przykłady, wyjaśnimy inne pojęcia, być może wydłużymy albo skrócimy poszczególne elementy.

Istnieje jednak kilka aspektów, na które powinniśmy zwrócić uwagę zawsze, niezależnie od grupy odbiorców. Tekst musi być zrozumiały - to oczywiste. Jednak co to tak naprawdę oznacza? Skąd mamy wiedzieć czy to, co właśnie napisaliśmy, będzie łatwe do przyswojenia?

Po pierwsze, powinniśmy zasięgnąć trochę wiedzy na temat wypracowanych metod skutecznej komunikacji. Dobrym przykładem będzie plain language - czyli zestaw wytycznych, które mówią wprost, co to znaczy, że tekst jest prosty. Koncepcję wykorzystują między innymi instytucje federalne w Stanach Zjednoczonych. Postawiły sobie za cel tworzenie dokumentów w taki sposób, aby były zrozumiałe dla możliwie szerokiego spektrum odbiorców - ludzi wykształconych, ale też tych, którzy nie ukończyli wyższych uczelni; ludzi z różnego rodzaju dysfunkcjami czy niepełnosprawnością; niezależnie od wieku czy klasy społecznej.

Drugim przykładem może być Specyfikacja ASD-STE100, precyzująca w jaki sposób należy przygotowywać dokumentację techniczną. Pierwotnym celem tego projektu było uproszczenie języka angielskiego tak, aby wszystkie techniczne aspekty były zrozumiałe nawet dla laika. Potrzeba została pierwotnie zgłoszona m.in. przez linie lotnicze. Zdecydowana większość pasażerów nie znała angielskiego na tyle, aby w pełni korzystać z ich usług czy stosować się do instrukcji (często związanych z bezpieczeństwem). Problemem była złożoność językowa, wieloznaczność i brak zrozumienia zagadnień związanych z branżą. Zachęcam do zapoznania się z tym podejściem.

W kwestii tworzenia lepszych tekstów możemy liczyć na wsparcie maszyn. Istnieje oprogramowanie pozwalające na analizę treści nie tylko pod kątem składni, ortografii, ale także pod kątem złożoności, prostoty formy, itd. Możliwości jest wiele, ale szczególnie polecam narzędzia: Hemingway Editor, acrolinx, readable.io czy HyperSTE.

Powyższe rozwiązania wymagają tworzenia dokumentacji w języku angielskim - najbardziej popularnym, międzynarodowym języku w obszarze technologii. Czasem konieczność tłumaczenia może wydłużyć czas pisania. Jednak w tym miejscu należałoby wspomnieć, że jeśli Twoim klientem może być ktoś zza granicy, warto zastanowić się czy angielski w dokumentacji nie będzie lepszym wyborem, niż Twój język ojczysty.

Dokumentacja jako część procesu?

Jeśli wiemy już w jakich sytuacjach potrzebujemy dokumentacji i jak ją pisać, warto zastanowić się, kiedy jest na to odpowiedni moment.

Wiele firm wybiera rozwiązanie, które zakłada, że zespół tworzący oprogramowanie współpracuje ze specjalnie zatrudnionym technical writerem. Jest to człowiek, który ma wykształcenie ukierunkowane na pisanie treści i komunikację. Zwykle ma też spore doświadczenie, dzięki któremu tworzone przez niego dokumenty cechują się wysoką jakością. Staje się on członkiem zespołu na czas przygotowywania danej funkcjonalności; rozmawia z zespołem o wymaganiach i potrzebach biznesowych, zbiera wiedzę na temat tego, jak zostały one zaimplementowane. Finalnie technical writer jest odpowiedzialny za dostarczenie dokumentów opisujących daną funkcjonalność czy cały produkt. W zależności od projektu, dokumentacja powstaje albo w trakcie realizacji, albo dopiero po jej zakończeniu. W obu przypadkach konieczne są liczne aktualizacje oraz czas potrzebny na weryfikację czy treść odpowiada temu, co zostało faktycznie zaimplementowane.

W DreamLabie podeszliśmy do tematu nieco inaczej. W naszych szeregach, póki co, nie ma technical writerów. Mamy natomiast ponad 300 deweloperów, dojrzałe procesy tworzenia i dostarczania oprogramowania oraz przyjętą i sprawdzoną metodologię pracy.

Założyliśmy, że potrzeba pisania dokumentacji nie może ingerować w cykl pracy deweloperów. Nie mogą oni zmieniać kontekstu, w którym aktualnie się znajdują, tylko po to, żeby napisać kawałek dokumentacji. Uznaliśmy, że skoro ich codzienna praca sprowadza się do tworzenia oprogramowania - pisania kodu - to dokumentacja też powinna być pisana jak kod. Koncepcja pisania dokumentacji w kodzie (w formie komentarzy), wykorzystywana zazwyczaj do tworzenia tzw. reference manuals (dokumentów opisujących poszczególne metody, funkcje), została przez nas rozszerzona na dokumentację użytkownika. Założyliśmy, że nic nie stoi na przeszkodzie, aby przechowywać w repozytorium dokumentację biznesową, manuale, tutoriale, itd. (polecam artykuł Pisz dokumentację tak jak kod). Zdecydowaliśmy się na prosty format - reStructuredText - który jest zrozumiały sam w sobie, jednocześnie pozwalając na generowanie dokumentów w przeróżnych formatach.

Deweloperzy, implementując daną potrzebę biznesową w formie kodu, równolegle piszą lub uzupełniają dokumentację. Wszystkie narzędzia znajdują się w jednym miejscu, przez co oszczędzają czas i mogą być na bieżąco ze zmianami. Kiedy wszystko jest gotowe, kod oraz dokumentacja są weryfikowane (przechodzą CodeReview) i wdrażane w ramach procesu ciągłego dostarczania oprogramowania (continuous development).

Reszta dzieje się sama. Proces dba o to, aby opublikować dokumentację w odpowiednim miejscu w momencie, kiedy wdrażana jest nasza funkcjonalność.

Podsumowanie

Dokumentacja jest potrzebna. Jest częścią produktu, ma wartość biznesową - pozwala ograniczyć koszty i pozyskiwać nowych klientów.

W zależności od zastosowania, odbiorcy czy skali projektu, może ona przybierać różne formy. Zazwyczaj pisanie dokumentacji nie wymaga tworzenia tysięcy dokumentów i skomplikowanego języka - treści powinny być proste i zrozumiałe dla jak największej grupy odbiorców. W idealnej sytuacji, dokumentacja może być częścią procesu tworzenia oprogramowania, co pozwala ograniczyć czas potrzebny na jej przygotowanie i publikację.

Nasz przykład - zmiana dotycząca dokumentacji w DreamLabie - pokazuje, że dzięki zaimplementowaniu kilku znanych i popularnych koncepcji możliwe jest pisanie dokumentacji rękami deweloperów. Kluczowe jest wpięcie się w istniejący cykl pracy i procesy wspierane w firmie.

Tworzenie dokumentacji to ciągły proces doskonalenia form komunikacji w oparciu o dotychczasowe doświadczenia. Dlatego już dziś mamy wiele nowych pomysłów jak zachęcić większą grupę ludzi do pisania, jak usprawnić narzędzia oraz jak wykorzystać te, których jeszcze nie wykorzystujemy.

Na koniec zostawię Cię z pytaniem. Jak wygląda proces tworzenia dokumentacji w Twojej firmie?

<p>Loading...</p>