Dokumentacja techniczna - jak ją prowadzić?

Podobnie jak GUI tworzonej przez nas aplikacji, dokumentacja techniczna to część produktu dostępna bezpośrednio dla klienta. Traktowana po macoszemu i postrzegana jako zło konieczne, staje się przysłowiowym piątym kołem, jednak przygotowana dobrze może podnieść wartość i użyteczność naszego produktu. Jak więc prowadzić dokumentację techniczną? Myślę, że...

Od zera

Problemem, który często dotyka dokumentację, jest źródło treści, która się w niej znajduje. Praca nad projektem generuje dziesiątki wewnętrznych dokumentów, których używamy we wszelkiego rodzaju analizach lub planach implementacji. Skoro zdążyliśmy opisać nasz produkt jeszcze zanim zabraliśmy się za przygotowanie właściwej dokumentacji, to dlaczego by nie użyć już istniejącej treści? Odpowiedź jest prosta: to nie jest treść odpowiednia dla klienta.

Dokumentacja wewnętrzna, poza oczywistymi „pułapkami” w postaci szczegółów technicznych, które wraz z taką dokumentacją mogą trafić do konkurencji, jest zwykle najeżona żargonem i skrótami myślowymi, powstałymi w toku pracy nad produktem. Zatem, zamiast poświęcać czas na filtrowanie istniejącej treści, warto stworzyć dokumentację od zera, w oparciu o potrzeby klienta. Można zacząć od listy prostych pytań: Jakie czynności muszę wykonać, aby produkt działał prawidłowo? Na jakie problemy mogę się natknąć podczas użytkowania? Jakich potrzebuję narzędzi?.

Mimo że wiedza zawarta w naszych dokumentach wewnętrznych pomoże nam odpowiedzieć na te pytania, to przygotowując dokumentację dla klienta, powinniśmy bardzo ostrożnie używać „Ctrl+C” i „Ctrl+V”. Skupmy się tylko na informacji, którą klient może faktycznie wykorzystać, unikajmy rozbudowanych opisów i przeładowania technicznymi detalami. Ciekawym pomysłem jest stopniowe wprowadzanie użytkownika w treść (ang. progressive disclosure). Według tej koncepcji użytkownik ma mieć dostęp tylko do informacji, która jest mu w danej chwili niezbędna do wykonania zadania. We fragmencie poświęconym podłączeniu zasilania, nie będziemy więc umieszczać tabeli z wymiarami urządzenia, lub informacji o czynności, którą użytkownik ma wykonać w późniejszym etapie instalacji.

Prowadząc użytkownika „za rękę” przez naszą treść unikamy obciążenia kognitywnego, wynikającego z konieczności wyszukiwania informacji w długich, skomplikowanych fragmentach tekstu, które często prowadzi do frustracji („skoro znalazłem interesujący mnie fragment, to dlaczego muszę szukać dalej?”).

Z duchem czasu

Dokumentacja techniczna jest często wyrwana z kontekstu współczesnych realiów informacji. Szczególnie dotyka to produkty specjalistyczne, z bardzo wąskim gronem odbiorców. Przygotowując treść opisującą takie produkty, często zapominamy, że nasi odbiorcy, niezależnie od wykształcenia czy poziomu zaawansowania, są również użytkownikami internetu: korzystają z portali społecznościowych, forów dyskusyjnych, czy serwisów informacyjnych.

Patrząc na media społecznościowe na przestrzeni ubiegłej dekady, trudno nie zauważyć kilku dominujących trendów. Twitter ograniczył liczbę znaków dostępnych użytkownikowi, zmuszając go do przekazywania treści w uproszczonej formie. Instagram postawił na obraz, jako podstawową formę komunikacji, traktując tekst zupełnie arbitralnie. Popularność zyskują infografiki, porządkujące treść w sposób wizualny. Wyszukujemy informacje przy pomocy słów-kluczy, czytając tylko te fragmenty, które zawierają interesujący nas termin.

Dokumentacja techniczna powinna również dopasować się do współczesnej rzeczywistości i nie chodzi tu o zamianę diagramów na selfies, ani o odrzucenie gramatyki i składni, jak ma to często miejsce w postach, które czytamy na co dzień. Należy potraktować wyżej wymienione przykłady jako wskazówki, drogowskazy wyznaczające kierunek, w którym zmierza współczesny świat informacji. Nawet jeżeli dokumentacja, którą tworzymy, nie będzie dostępna dla wszystkich w internecie, warto zastanowić się, czy umieszczona tam spełniłaby wszystkie wymogi wyszukiwania i łatwości dostępu. Zobaczymy wtedy, że poświęcenie pięciu stron teoretycznym aspektom konfiguracji adresu IP, to niekoniecznie dobry pomysł.

Tak jak kod

Era tradycyjnych edytorów tekstu skończyła się wiele lat temu. Współczesne narzędzia wykorzystywane w procesie tworzenia i publikacji dokumentacji technicznej zbliżyły się bardzo do tych, z których korzystają software developers. Popularnym standardem współczesnej dokumentacji jest Darwin Information Typing Architecture (DITA), bazujący na XML. DITA wprowadza model informacji, który dzieli treść na trzy podstawowe kategorie: concept, czyli opis;  task, czyli instrukcja; oraz reference – informacje pomocne przy wykonaniu zadania.

DITA odrzuca klasyczny schemat dokumentu, który czytamy od początku do końca, na rzecz informacji złożonej z bloków  – topics. Każdy topic odpowiada na pytanie, instruuje jak wykonać zadanie, lub zbiera informacje na temat pojedynczego zagadnienia. Każdy topic jest osobnym plikiem XML, a zawarte w nim informacje mają być wyczerpujące i zawarte w sposób, który pozwala na umieszczenie go w różnych formach (publikacjach), jako pomoc kontekstowa, pomocą zintegrowana bezpośrednio z interfejsem graficznym aplikacji, czy dokument PDF lub HTML.

Modularna struktura i odejście od narracji, znanej z wielu form tekstu pisanego, upodabnia tworzenie dokumentacji do pisania kodu. Podobieństw jest więcej. Dokumentacja tworzona w DITA może być aktualizowana w sposób niemal natychmiastowy. Jeżeli nasza dokumentacja jest dostępna online, posiadamy system do zarządzania treścią (content management system) i narzędzia umożliwiające dynamiczną publikację, wystarczy, że edytujemy interesujący nas topic, opublikujemy zmiany na serwerze i nie musimy martwić się pozostałą treścią. W końcu przygotowaliśmy nasz blok tekstu w taki sposób, by mógł być dowolnie przemieszczany. Dzięki szablonom i użyciu tagów nie musimy też zaprzątać sobie głowy formatowaniem i wyglądem tekstu po opublikowaniu – zrobi to za nas stylesheet.

Pojawienie się i ewolucja standardów takich jak DITA to kolejny dowód na to, że współczesny świat informacji poszukuje jak najkrótszej drogi do osiągnięcia celu użytkownika, przy jednoczesnym skróceniu czasu, potrzebnego na dostarczenie aktualnej treści.

Szczerze i bez lęku

Dokumentacja techniczna ma nie tylko informować czy prowadzić użytkownika przez proces instalacji i konfiguracji – ma za zadanie również ostrzegać. Pogodzenie tych funkcji nie jest łatwo. Niejednokrotnie odniosłem wrażenie, że dokumentacja skonstruowana była niczym solidny falochron, mający chronić nie tyle użytkownika, co producenta przed ewentualnymi pozwami sądowymi, wynikającymi z niewłaściwego użytkowania.

Większość z nas słyszała o głośnych sprawach, jak np. ta klienta znanej sieci fast food, który poparzył się kawą, bo na kubku nie było informacji, że kawa jest za gorąca. Kultura zadośćuczynienia (ang. compensation culture), doprowadziła do sytuacji, w których dokumentacja potrafi się zamienić w wielki znak „STOP”.

Podobnie jak w innych aspektach prezentacji treści, ważne jest odpowiednie wyważenie poszczególnych funkcji, które ta treść ma pełnić. Ostrzeżenia o potencjalnych zagrożeniach to stały element dokumentacji, nie pozwólmy jednak tej treści zdominować inne informacje. Przeładowanie treści ostrzeżeniami i wyjątkami od ogólnie przyjętych zasad nie tylko tworzy obraz niedopracowanego produktu, ale i sprawia, że poszczególne ostrzeżenia tracą swoją ważność, giną między setką innych, sobie podobnych. Jeżeli przygotowywana przez nas informacja wymaga od nas ostrzegania użytkownika na każdym kroku, to może warto jeszcze raz przyjrzeć się samemu produktowi? Może wypadałoby go poprawić?

Z oczami na świat

Mimo specyfiki treści dokumentacji technicznej można śmiało pokusić się o stwierdzenie, że treść ta podlega takim samym prawom jak każda inna dostępna współcześnie informacja. Mimo że świat dokumentacji reaguje na nowinki z pewnym opóźnieniem, to nie jest na nie zupełnie odporny. Prostota, funkcjonalność, łatwe wyszukiwanie, łatwość w zarządzaniu, a przede wszystkim użyteczność, to słowa-klucze, które pozwolą nam na stworzenie dokumentacji, która będzie wartością dodaną do naszego produktu. Nie bójmy się czerpać ze schematu wypracowanego przez nowoczesne media, nie bójmy się eksperymentować. Przede wszystkim jednak wsłuchajmy się w potrzeby klienta i piszmy taką dokumentację, jaką sami chcielibyśmy czytać.

O autorze:

Mateusz Szczurek pracuje w Ericsson już 2,5 roku i zajmuje obecnie stanowisko Documentation Specialist. Jego pasją jest muzyka. Współtworzy krakowski zespół Fleshworld, w którym gra również na gitarze. Tworzy również muzykę elektroniczną. Poza tym pasjonuje się lotnictwem.