Najczęstsze błędy w dokumentacji technicznej – jak ich unikać?

Dokumentacja techniczna w projektach jest często traktowana jako coś drugorzędnego – coś, co musi istnieć, ale nie poświęca się jej takiej samej uwagi, jak samemu produktowi. Jednak w rzeczywistości dokumentacja jest równie ważna jak kod, projekt czy testy. Stanowi pomost między twórcami a użytkownikami, między programistami a przyszłymi administratorami, między zespołem a interesariuszami. Dobra dokumentacja pomaga zespołom w skalowaniu, szybszym wdrażaniu nowych osób i unikaniu powtarzania błędów.

Z drugiej strony, źle napisana dokumentacja kosztuje czas, pieniądze i wiele nerwów. Za każdym razem, gdy ktoś nie może znaleźć odpowiednich informacji, źle rozumie instrukcje lub powiela pracę z powodu wadliwej dokumentacji, projekt traci na wydajności.

Ten artykuł jest przeznaczony nie tylko dla Technical Writerów – jest dla wszystkich, którzy mają swój wkład w tworzenie dokumentacji:

• programistów,
• menedżerów,
• Product Ownerów,
• Scrum Masterów,
• specjalistów PMO,
• a nawet stakeholderów, którzy pomagają kształtować wymagania.

Niezależnie od tego, czy dopiero zaczynasz, czy już zarządzasz dokumentacją projektową jako starszy specjalista, poniższe wskazówki pomogą Ci uniknąć najczęstszych pułapek. 

Brak spójności językowej i strukturalnej tekstu

Pierwszym, choć nie najważniejszym błędem, jest brak spójności językowej i strukturalnej tekstu. Każdy człowiek ma inny styl pisania, jednak niezachowanie pewnych stałych zasad może wprowadzać chaos do dokumentu. Co więcej, gdy autorów w projekcie jest kilku i każdy tworzy po swojemu, cała grupa dokumentów może zawierać różny styl, układ i terminologię. Jedna sekcja może zawierać zdania rozkazujące, a inna opisowe. Jedna instrukcja może zawierać listę kroków z numerami, a druga z punktami. Niektórzy wolą zrzuty ekranu, inni diagramy.

Taki brak logicznego uporządkowania treści prowadzi do trudności w odnajdywaniu informacji zarówno dla obecnych, jak i nowych współpracowników, obniża wiarygodność dokumentacji oraz sprawia, że czytelnik marnuje czas na interpretację tekstu zamiast na właściwe działanie. Z czasem, nawet dla samych autorów taki zbiór plików jest trudny w utrzymaniu.

Rozwiązanie

Jak sobie zatem z tym poradzić? Przede wszystkim, warto korzystać z gotowych szablonów dokumentów. Duże firmy i korporacje zazwyczaj mają je przygotowane do wielu różnych typów dokumentacji.

Dobrą metoda na zachowanie spójności w tekście jest także korzystanie ze style guide’ów dostępnych w Internecie. Najbardziej popularne miejsca opisujące dobre praktyki pisania to:

• Microsoft Writing Style Guide,
• Google Developer Documentation Style Guide.

Technical Writerów zainteresuje też społeczność Write the Docs.

Warto również wybrany styl pisania podsumować w checklistę i korzystać z niej za każdym razem, np. podczas wzajmnego sprawdzania tekstów. 

Dokumentacja powinna uwzględniać z góry ustalony i regularnie aktualizowany słownik pojęć projektowych.

Spójność jest niewidoczna, gdy jest dobrze wykonana, ale boleśnie oczywista, gdy jej brakuje. 

Ignorowanie odbiorcy

Drugi błąd popełniany podczas tworzenia dokumentacji to ignorowanie odbiorcy. Podstawowym przejawem jest zakładanie, że czytelnik posiada taki sam poziom wiedzy i zrozumienia treści, co jej autor. 

W teorii brzmi to, jak coś oczywistego, jednak często sami nie zdajemy sobie z tego nawet sprawy. W szczególności po dłuższym czasie pracy nad jednym projektem czy aplikacją, kiedy wiele terminów, skrótów i pojęć staje się logicznych i łatwych dzięki codziennemu użytkowaniu. Takie używanie specjalistycznego żargonu, choć może wydawać się bardziej profesjonalne dla autora, czy nawet innych „starych” pracowników, zdecydowanie nie jest dobre dla tych nowych.

Podobnie pomijanie kontekstu, również znajomego dla obecnych członków zespołu, prowadzi do gorszego zrozumienia przez nowego odbiorcę. Taka dokumentacja napisana dla samego siebie, zamiast dla użytkownika, jest nie tylko nieczytelna, a wręcz może stać się bezużyteczna dla nowych pracowników czy klientów. Wiedza w nich zawarta pozostaje zamknięta w wąskim gronie specjalistów.

Rozwiązanie

Rozwiązań tego problemu mamy kilka. Po pierwsze, dobrą praktyką jest tworzenie person odbiorców dokumentacji, np. programista, tester, analityk biznesowy, czy (zazwyczaj najważniejszy) użytkownik końcowy.

Dalszym krokiem w tym obszarze może być testowanie dokumentacji z rzeczywistymi jej odbiorcami, poprzez zwyczajne poproszenie kolegów o przejście instrukcji. Podobnie, warto zastosować feedback loop, czyli wzajemne sprawdzanie swoich tekstów w zespole i dzielenie się poprawkami i komentarzami czy flagowanie niejasnych fragmentów. 

Ostatnim, dość oczywistym, ale niekoniecznie prostym rozwiązaniem, jest używanie języka dopasowanego do odbiorcy, klarownych i szczegółowych instrukcji oraz jednoznacznych przykładów. Dokumentacja powinna odpowiadać nie tylko na pytanie, jak coś zrobić, ale także dlaczego i dla kogo. 

Nieaktualna dokumentacja

Kolejnym błędem, który raz już poniekąd wspomniałam, jest nieaktualna dokumentacja. Projekty podlegają wielu szybkim zmianom, a dokumenty pozostają w tyle. Zmieniają się funkcje, kod ewoluuje, a interfejsy API stają się przestarzałe. Nikt jednak nie aktualizuje treści w plikach projektowych. Podręcznik czy instrukcja napisane kilka miesięcy temu, a co więcej, kilka releasów temu, po prostu już nie pokrywają się z rzeczywistością.

W konsekwencji, czytelnicy tracą zaufanie zarówno do treści, jak i do jej autorów czy kierowników projektu. Jeśli przeczytają jedną błędną stronę, założą, że pozostałe również takie są. Jednocześnie dokumentacja traci wartość i sens merytoryczny, a wręcz sens istnienia, zamieniając się w zmarnowany wysiłek. 

Najważniejsze jednak w kontekście nieaktualnych dokumentów jest powstanie długu technologicznego, który zmusza zespoły do uczenia się na własnych błędach i wracanie do początków, żeby przejść przez proces ponownie.

Rozwiązanie

Wbrew pozorom zapobieganie temu problemowi jest stosunkowo proste. Podstawowa zasada to wyznaczenie właściciela dokumentacji: osoby lub osób odpowiedzialnych za każdą jej część. Jeśli dokumenty są częścią pracy projektowej opartej na zadaniach wykonywanych w sprintach, warto uwzględnić aktualizację ich treści w Definition of Done. Tym sposobem, żadna funkcja nie będzie kompletna, dopóki nie zostanie zaktualizowana dokumentacja.

Dobrą praktyką jest także korzystanie z narzędzi, które łączą dokumenty z bazą kodu,np. GitHub, GitLab, Markdown. Najlepsza dokumentacja jest nie tylko dobrze napisana, ale także aktualizowana na bieżąco. 

Brak kontroli jakości dokumentów

Brak kontroli jakości dokumentów to prawdopodobnie największa zmora Technical Writerów. Niestety, dokumentacja często jest publikowana bez jakiejkolwiek weryfikacji. Oznacza to, że literówki, luki logiczne lub błędy techniczne pozostają niezauważone, dopóki nie frustrują czytelników.

W przeciwieństwie do kodu, gdzie weryfikacja przez innych i testowanie są projektowym standardem, dokumentacja czasami całkowicie pomija proces walidacji. Jeśli nikt nie sprawdza, co zostało napisane, odbiorca treści nie tylko może nie znaleźć wymaganych informacji, ale wręcz zostać wprowadzony w błąd, co miewa bardzo negatywne skutki – od niezadowolenia do generowania błędów w korzystaniu z aplikacji czy programu.

W konsekwencji, błędy mnożą się i są powielane w innych dokumentach. Czytelnicy tracą czas na prośby o wyjaśnienia, a zespoły narażają się na nieporozumienia i powtarzające się pomyłki.

Rozwiązanie

Rozwiązaniem jest wprowadzenie procesu weryfikacji: każdy dokument powinien zostać sprawdzony przez co najmniej jedną osobę. Dodatkową pomoc mogą stanowić tutaj wspomniane wcześniej checklisty.

Warto korzystać też z narzędzi wspierających jakość: sprawdzanie pisowni, np. Grammarly, WriteGood Linter. W przypadku dokumentacji technicznej, łatwo przyswajalnym przez zespoły deweloperskie rozwiązaniem są pull requesty Git – traktowanie dokumentów jak kodu, z taką samą rygorystycznością. Kontrola jakości nie jest biurokracją – to zabezpieczenie. 

Zbyt rozbudowana lub zbyt ogólna treść

Ostatnim, choć nie najmniej ważnym błędem, jest zbyt rozbudowana lub zbyt ogólna treść. Niektóre dokumenty są za długie i skomplikowane, próbują omówić wszystko w nieskończonej szczegółowości, przytłaczając czytelnika. Inne pozostają zbyt krótkie albo ogólnikowe, nie dostarczając żadnych praktycznych informacji, a będąc wręcz do niczego nie przydatne.

Obie te skrajności nie służą odbiorcom. Prowadzi to do zagubienia się użytkownika i nie zalezienia przez niego pożądanych informacji czy odpowiedzi. Taki czytelnik przestaje korzystać z dokumentacji, po krótkim czasie poddaje się i woli zapytać kogoś o rozwiązanie problemu. W efekcie, marnowany jest czas co najmniej dwóch osób, choć zwykle nawet i więcej.

Rozwiązanie

Żeby temu zapobiec, ważne jest stosowanie zasady „wystarczającej dokumentacji” (ang. „just enough documentation”), czyli pisanie tylko tego, co konieczne. W długich dokumentach, dobrze jest podzielić treść na moduły: rozbić złożone tematy na mniejsze, łatwe do przeglądania fragmenty.

Można też dodać sekcje TL;DR („too long, didn’t read”), czyli podsumowania na początku poszczególnych fragmentów, aby ułatwić szybkie zapoznanie się z treścią.

Dodatkowo, używanie indeksów, tabel, diagramów, czy innych elementów graficznych pomaga czytelnikom zorientować się w treści. Dobra dokumentacja to nie ta, która zawiera wszystko – to ta, która odpowiada na rzeczywiste potrzeby czytelnika. 

Najlepsze praktyki pisania dokumentacji

Jakie zatem są najlepsze praktyki pisania skutecznej dokumentacji? Na podstawie sześciu lat doświadczenia jako Technical Writer, przygotowałam kilka najbardziej praktycznych wskazówek, które zawsze się sprawdzają: 

• Korzystanie z checklist: Sprawdzenie gramatyki, struktury, dokładności i dostosowanie do odbiorców przed publikacją. 
• Formatowanie tekstu tak, aby był czytelny: Podzielenie tekstu na nagłówki, podtytuły i akapity, używanie pogrubienia dla kluczowych punktów. 
• Wykorzystanie narzędzi: Confluence do wspólnej edycji, GitHub do dokumentów związanych z kodem, Markdown do lekkich i przenośnych treści. 
• Zaangażowanie zespołu: Dokumentacja jest wspólnym obowiązkiem. Programiści mogą wnieść wiedzę techniczną, testerzy mogą zweryfikować poszczególne kroki, a menedżerowie mogą zapewnić zgodność z celami biznesowymi. 
• Dbanie o dostępność dokumentów: Idealny dokument ukryty głęboko w systemie jest bezużyteczny. Organizowanie, oznaczanie i tworzenie odnośników to podstawa. 

Podsumowanie

Dokumentacja nie powinna być traktowana jak zadanie domowe – powinna być naturalnym uzupełnieniem produktów, projektów i aplikacji. 

 Podsumowując, oto pięć najczęściej popełnianych błędów w dokumentacji: 

1. Brak spójności – rozwiązanie: style guide’y, szablony i recenzje. 
2. Ignorowanie odbiorców – rozwiązanie: persony, testowanie i feedbacki. 
3. Nieaktualna dokumentacja – rozwiązanie: odpowiedzialność i integracja z cyklami sprintów. 
4. Brak kontroli jakości – rozwiązanie: procesy i narzędzia recenzji. 
5. Zbyt duża lub zbyt mała ilość treści – rozwiązanie: równowaga, modułowość i TL;DR. 

Wniosek jest prosty: dokumentacja nie jest tylko produktem ubocznym – jest istotną częścią produktu. Im bardziej traktowana jest z szacunkiem i strukturą, tym więcej korzyści odniesie zarówno zespół, jak i klienci. Zacząć można już od małych kroków: wprowadzenie szablonów, zaplanowanie regularnych przeglądów, przydzielenie odpowiedzialności. Z czasem dokumentacja przestanie być ciężarem, a stanie się prawdziwym atutem. 

Źle napisana dokumentacja kosztuje czas i nerwy. Dobra dokumentacja oszczędza jedno i drugie – i sprawia, że projekt wygląda profesjonalnie. Wybór należy do Ciebie.