Jak napisać dobrą dokumentację techniczną aplikacji? Porady i konkretne przykłady
Dobra dokumentacja techniczna krok po kroku
Zanim zaczniemy pisać dokumentację techniczną naszej aplikacji…
Wstęp pełen banałów, które - jak się okazuje - wcale banałami nie są
Mało który programista lubi pisać dokumentację techniczną i niniejszy artykuł nie ma zamiaru przekonywać Cię do tego, że pisanie dokumentacji to najfajniejsze zadanie pod słońcem.
Prosimy Cię tylko o jedno — nie zaczynaj pisać dokumentacji z następującym nastawieniem:`
“Było trudno napisać aplikację,
to niech i trudno będzie ją zrozumieć.”
Bo przecież dokumentacja techniczna powinna być jak instrukcja obsługi — konkretna, czytelna, rozwiewająca wątpliwości, pokazująca użytkownikowi krok po kroku, gdzie wmontować którą śrubkę oraz jak korzystać ze zmontowanego sprzętu.
A jeżeli już przychylasz się do tej pierwszej prośby, to mamy i drugą: nie odkładaj pisania dokumentacji technicznej “na ostatnią chwilę”. Z tego nigdy nic dobrego nie wychodzi. Po pierwsze, po trzech miesiącach programowania nawet Twój własny kod będzie wyglądał obco. Po drugie, pisana “po łebkach” dokumentacja sprawi tylko, że w kolejnych miesiącach na skrzynce działu technicznego mnożyć będą się mało życzliwe maile od zdenerwowanych programistów, którzy poświęcili godziny swojego czasu na rozwiązaniu jakiegoś problemu i nic ich nie obchodzi, że “u Ciebie wszystko działa”, bo u nich nie działa a z dokumentacją coś jest nie tak.
W zamian, wprowadź w swój tok pracy nad aplikacją dobry nawyk: w każdym tygodniu spędzam 2–4h na tworzenie dokumentacji i jej uaktualnianie. Niech to będzie czas wpisany jasno w harmonogram pracy zespołu.
Jak napisać dobrą dokumentację techniczną aplikacji
Krok 1: Zrozumienie, kto tak naprawdę jest odbiorcą dokumentacji, czyli wybór stylu pisania
Istnieją trzy podstawowe sytuacje, gdy ktoś otworzy Twoją dokumentację:
- Jest ciekawy jak aplikacja działa i co oferuje,
- Bardzo chce zacząć z niej korzystać,
- W trakcie korzystania z aplikacji utknął na jakimś etapie i potrzebuje pomocy.
Innymi słowy, na stronie Twojej dokumentacji technicznej wyląduje albo osoba decyzyjna tudzież Project Manager albo — dużo częściej — programista, którego zadaniem jest wdrożenie aplikacji po stronie Klienta.
Dlatego polecamy pisać dokumentację techniczną, tak jakby jej czytelnikami byli programiści.
Co za tym idzie, styl pisania dokumentacji powinien być techniczny i konkretny. Używaj krótkich treściwych zdań bez upiększeń. Całość musi być czytelna już na pierwszy rzut oka i logiczna.
Jak napisać dobrą dokumentację techniczną aplikacji
Krok 2: Niezbędne elementy dokumentacji technicznej, czyli tworzenie spisu treści
Każda aplikacja jest inna. Jedna krótsza, druga dłuższa. Stąd niektóre dokumentacje techniczne zajmują dwie strony A4, a inne swoim woluminem przypominają Encyklopedię Britannica. Istnieją jednak podstawowe elementy, które przyjmuje się zawrzeć w każdej dokumentacji technicznej.
Co musi się znaleźć w dokumentacji:
- wstęp, czyli opis sposobu działania (konkretnie: co robi ta appka),
- sposób instalacji aplikacji i zależności,
- zastosowane algorytmy,
- rozmieszczenie i sposoby działania poszczególnych komponentów.
To, co musimy zatem zrobić na wstępie pisania dokumentacji technicznej, to rozrysować jej spis treści. Co, gdzie i w jakiej kolejności, tak żeby każdy istotny element można było łatwo i szybko znaleźć bez względu na to, czy zaglądamy do tej dokumentacji po raz pierwszy, próbując zacząć z niej korzystać czy też wracamy do niej po latach z jakimś bugiem.
Poniżej wrzucamy kilka inspirujących przykładów spisu treści dokumentacji technicznej, które powalają swoją czytelnością i przyjazną dla użytkownika nawigacją.
Spis treści dokumentacji technicznej — przykłady
Przykład 1. Heroku Dev Center
Dokumentacja techniczna Heroku pod względem spisu treści to jeden z najlepszych przykładów na rynku.
Od razu z miejsca widzimy główne kategorie — od architektury przez bazy danych, bezpieczeństwo, linie komend i dodatki aż po języki supportu. Poniżej głównych linków dodatkowo mamy wylistowane w trzech kolumnach wszystkie elementy wchodzące w skład każdej z głównych kategorii. Żadnego rozwijania czy zwijania elementów. Wszystko podane na tacy.
Przykład 2. Laravel
Całkowicie inny układ spisu treści (ale równie wygodny w użyciu) proponuje Laravel.
Główne kategorie zostały wypisane na lewym bocznym pasku strony z dokumentacją, a każdą z kategorii i jej menu otwieramy plusikiem. Podmenu, na którym w danym momencie się znajdujemy, wyróżniono dodatkowo czerwonym kolorem, co ułatwia nawigację.
Jak napisać dobrą dokumentację techniczną aplikacji
Krok 3: Opisanie poszczególnych komponentów i zamieszczenie przykładów zastosowania (koniecznie z fragmentami kodu!)
Gdy mamy już uporządkowane menu naszej dokumentacji technicznej, przechodzimy do opisania poszczególnych elementów.
Na początek wstęp, czyli kilka zdań wytłumaczenia do czego służy aplikacja.
Można to zrobić jednym akapitem, opisując podstawowe działanie, tak jak np. Stripe Sigma:
Lub możemy opisać całość jednym prostym zdaniem, np. “Ta aplikacja pozwala uzyskać dostęp do bazy danych YXC, na podstawie których przewidzisz ile prezentów dostaniesz od swoich znajomych w najbliższym roku”.
Następnie przechodzimy do opisania konkretnych metod działania programu oraz zastosowanych komend.
Co ważne, każdą komendę warto podeprzeć przykładem z kodem!
Dlaczego? Uzasadnienie jest proste:
- przykłady szybciej tłumaczą zasadę działania niż rozległe opisy tekstowe, a skoro czytelnikami naszej dokumentacji technicznej są programiści, z pewnością docenią wklejone fragmenty kodu,
- przykłady kodu to również gotowe elementy kopiuj-wklej. W ten sposób użytkownicy mogą od razu wykorzystać w praktyce dane linijki bez konieczności rozpracowywania wszystkiego własnym wysiłkiem.
Opis metod działania z wklejonym fragmentem kodu — przykłady
Przydatna wskazówka:
Warto stopniować metody od najłatwiejszej do najtrudniejszej. W ten sposób, dopiero po 3–5 łatwiejszych przykładach (np. test uwierzytelniania czy prosty request) opisujemy metody bardziej skomplikowane. Dzięki temu, programista najpierw zostaje zachęcony sukcesami pierwszych prób, a dopiero później staje przed trudniejszymi wyzwaniami. Łatwiej mu wtedy przetworzyć nowe informacje.
Jak napisać dobrą dokumentację techniczną aplikacji
Krok 4: Nie bój się sięgać po przydatne narzędzia, czyli z których generatorów dokumentacji technicznej warto korzystać
Nie zawsze wszystko trzeba robić ręcznie. Nie żyjemy wszak w XVII wieku ;) Generator dokumentacji technicznej to nieocenione narzędzie, które automatycznie konwertuje pliki źródłowe za nas i wrzuca je do HTML lub dowolnego innego pliku wyjściowego. Znacznie przyspiesza to tworzenie dokumentacji technicznej.
W ostatnich latach generatorów dokumentacji technicznej pojawia się na rynku coraz więcej i więcej. Tutaj podpowiadamy, które naszym zdaniem są obecnie w zdecydowanej czołówce.
TOP 3 darmowe generatory dokumentacji technicznej, które zapewniają wsparcie dla takich języków programowania jak. m.in. C++, C, Objective-C, C#, PHP, Java, Python i IDL:
Z pewnością któryś z nich podbije Twoje serce ;)
“Win-Win situation” — wygrywasz i Ty i Twój Klient
Korzyści z dobrze napisanej dokumentacji technicznej:
- mniej próśb o pomoc techniczną ( rozwiązywanie problemów technicznych trwa zazwyczaj dłużej niż pisanie dokumentacji!),
- wymiana negatywnych maili na pozytywne (nie psujemy krwi i nastroju Klientom i sami nie podnosimy sobie ciśnienia, czytając zażalenia),
- mamy porządną podwalinę pod rozwój kolejnych produktów (skalowanie i takie tam istotne strategicznie dla rozwoju sprawy),
- zadowoleni Klienci, a zatem więcej poleceń, więcej kontraktów i więcej zysku dla firmy.
Mogą Cię zainteresować też inne artykuły z naszego cyklu Tech Stories:
