Dobra dokumentacja - cechy i etapy tworzenia

Dla jednych pisanie dokumentacji to droga przez mękę, dla innych czysta przyjemność i sposób zarabiania na życie. Jednak zarówno ci pierwsi jak i drudzy powinni trzymać się pewnych reguł. Dziś pierwszy z cyklu artykułów, które, mamy nadzieję, pomogą Wam utrzymać jak najwyższy poziom tekstów, a także sprawią, że pisanie nie będzie już takie straszne (dla niektórych) 😉.

Cechy dobrej dokumentacji

Dobra dokumentacja jest:

• kompletna - nie brakuje w niej żadnej informacji istotnej dla użytkownika,
• spójna - taka, która stanowi harmonijnie połączoną całość,
• dokładna - starannie napisana z dbałością o szczegóły,
• bezbłędna - w pełni poprawna,
• zrozumiała - dostosowana do odbiorcy tak, że jest w stanie zastosować opisane procedury,
• przejrzysta - struktura dokumentacji jest przewidywalna dla użytkownika,
• estetyczna - prawidłowo i poprawnie sformatowana, utrzymana w wizualnym stylu preferowanym przez firmę,
• zgodna z zasadami panującymi w organizacji - napisana zgodnie z podręcznikiem stylu oraz wszelkimi wytycznymi czy przepisami, które są narzucone np. przez branżę firmy.

Jeśli według Was coś jeszcze powinno znaleźć się na tej liście - zapraszamy do komentowania.

A jeśli macie ochotę poszerzyć temat cech dobrej dokumentacji zapraszamy do zapoznania się z artykułem Siedem zasad projektowania pomocy dla użytkownika w 2017 roku.

Etapy tworzenia dokumentacji

Aby dokumentacja była dobra, należy odpowiednio rozplanować pracę już od samego początku. Poniżej lista kroków, jakie warto zrobić, by stworzyć porządny tekst..

1. Tworzenie planu dokumentacji. Dobry plan to połowa sukcesu w tworzeniu dobrej dokumentacji. Jakie powinien mieć elementy?
   • Tytuł,
   • imię i nazwisko Technical Writera,
   • określenie typu dokumentacji (instrukcja, online help),
   • określenie daty zakończenia pracy nad dokumentacją,
   • krótki opis tego, czego dotyczy dokumentacja,
   • oszacowanie liczby stron - można wykorzystać do tego istniejące dokumenty o podobnej tematyce,
   • spis rozdziałów,
   • określenie etapów weryfikacji tekstu w trakcie prac.
2. Zbieranie informacji na dany temat. W celu uzyskania jak najdokładniejszych informacji na interesujący nas temat często korzystamy z wielu dostępnych źródeł wiedzy, jak na przykład już istniejąca dokumentacja. Jeśli opisujemy program informatyczny, działanie jakiejś maszyny czy choćby instrukcję złożenia regału, zazwyczaj dobrym pomysłem jest postawienie siebie w roli użytkownika i przetestowanie produktu, o którym będziemy pisać. Czeka nas także szereg konsultacji z osobami tworzącymi przedmiot naszego zainteresowania.
3. Pisanie według ustalonego planu. Rozpoczynając pisanie należy zawsze pamiętać o adresacie tekstu. Inaczej napiszemy tekst dla programisty tworzącego system, a inaczej dla jego użytkownika. Dlatego też warto dbać o odpowiedni styl, słownictwo oraz poziom szczegółowości, który bardzo wpływa na zawartość tekstu. Na przykład: czy tłumaczymy gdzie są zmienne środowiskowe Windows (dla zwykłego użytkownika), czy tylko piszemy "zmień zmienną środowiskową X na Y" (dla programisty). Z naszego doświadczenia wynika także, że nie ma co zakładać iż napiszemy tekst punkt po punkcie według planu. Często zdarza się, że by napisać kolejny fragment musimy czekać na spotkanie z ekspertem, który obecnie nie ma dla nas czasu. Dlatego warto rozpisać główne rozdziały na bardziej szczegółowe podrozdziały, by móc tworzyć tekst, nawet wtedy gdy przez jakiś czas nie mamy pełnych danych. Dodatkowo, uzupełnianie takiej struktury w łatwy sposób pokazuje postępy w pracy - miejsca, które są już gotowe oraz te, które wymagają uzupełnienia lub zupełnie stoją w miejscu. Przykładem narzędzia, które umożliwia taką nieliniową edycję tekstu jest opisywany przez nas Scrivener (link 1 i link 2 do poprzednich artykułów).
4. Weryfikacja stworzonego tekstu. Poprzez weryfikację rozumiemy sprawdzenie pisanego tekstu pod kątem błędów (zarówno stylistycznych jak i merytorycznych) oraz sprawdzenie czy załączone zdjęcia/zrzuty ekranu (jeśli są) odpowiadają temu o czym w danym miejscu piszemy. Warto zarezerwować sobie czas na wykonanie instrukcji czy procedur, o których piszemy i sprawdzenie czy odnoszą oczekiwany skutek. To także dobry moment by oddać tekst do recenzji - zarówno komuś, kto jest ekspertem w danej dziedzinie jak i laikowi, który da nam feedback czy tekst jest zrozumiały. Jeśli jest tylko taka możliwość warto poprosić o to: kolegę Tech Writera (sprawdzi tekst pod kątem poprawności i stosowania dobrych praktyk), SME (sprawdzi prawdziwość informacji technicznych) oraz Product Managera/Analityka Biznesowego (da znać czy w dokumentacji jest wszystko czego może oczekiwać klient oraz czy wszystkie kluczowe funkcje produktu zostały poprawnie opisane). Niektóre firmy formalizują proces sprawdzania wprost wyróżniając dwie odrębne fazy:
   • weryfikacja tekstu pod kątem błędów, zgodności ze style guidem oraz praktykami obowiązującego w firmie,
   • testy dokumentacji pod kątem problemów technicznych - aktywne linki, poprawność formatowania, działanie nawigacji oraz czy dokument jest dostępny tam, gdzie powinien się znajdować
5. Poprawki oraz uzupełnianie luk.

Punkty 4. i 5. zazwyczaj powtarzamy kilka razy, zanim osiągniemy zamierzony cel, a nasz tekst spełni wszystkie cechy dobrej dokumentacji.

Zachęcamy także do zapoznania się z trzecią sekcją syllabusa ITCQF, w której znajdziecie bardziej szczegółowe informacje na temat etapów tworzenia dokumentacji.

W kolejnym odcinku: struktura dokumentu. Już dziś serdecznie zapraszamy.