Podstawy? Dekalog? Tak, wiem, główną grupą docelową tej strony są raczej tzw. starzy wyjadacze. Stąd kilka słów wstępu, zanim przeczytacie zasadniczą część dzisiejszego artykułu.
Jeśli czytaliście mój poprzedni tekst, wiecie, że od jakiegoś czasu jestem adeptką sztuki techwriterskiej. Jej arkana przyswajam na kierunku komunikacja techniczna w Akademii Finansów i Biznesu Vistula, gdzie od czasu do czasu dostaję mniej lub bardziej absorbujące zadania domowe. Napisanie artykułu pt. "Dekalog techwritera" było jednym z takich zadań w ramach przedmiotu "Praca z tekstem technicznym". Artykuł miał być krótki (maksymalnie jedna strona A4) i treściwy, a jednocześnie użyteczny zarówno dla początkujących, jak i nieco bardziej zaawansowanych dokumentalistów. Po przesłaniu tekstu do wykładowcy (pozdrawiam Daniela Barrio Fierro) otrzymałam entuzjastyczny feedback wraz z zachętą do ewentualnej publikacji. Ponieważ wykładowcom się nie odmawia 😉 artykuł ląduje niniejszym na gościnnych łamach Techwritera. Dla większości z was nie ma w nim zapewne niczego przełomowego, ale warto, aby nawet zaawansowani wrócili do korzeni :-)
Dla wzbogacenia całości znajdziecie tu także linki do starszych artykułów na ten temat - na pewno z przyjemnością je sobie przypomnicie. No i last but not least: na tej stronie ukazał się już kiedyś Dekalog Techwritera - dłuższy i bardziej wyczerpujący. Zajrzyjcie do niego, jeśli po poniższej lekturze poczujecie niedosyt i będziecie chcieli dodatkowo pogłębić temat.
A zatem - jedziemy!
Zanim zaczniesz tworzyć dokumentację…
- Ustal, jaki jest cel tworzonej przez Ciebie dokumentacji oraz kim jest jej odbiorca - przestudiuj istniejące persony lub stwórz je od nowa.
- Wstaw się w położenie swojego odbiorcy - przestudiuj ścieżkę klienta i podejdź do niej empatycznie.
- Zawsze starannie mapuj informacje - co wiesz, a czego nie wiesz? Gdzie są Twoje źródła? Kogo możesz poprosić o pomoc?
- Przemyśl kształt i strukturę treści (video? instrukcja z ikonkami? tekst?), a następnie przygotuj konspekt. Dobry plan jest pomocny i obejmuje nie tylko pomysły na ułożenie treści, ale też to, jakich narzędzi będziesz używać do stworzenia dokumentacji oraz ile czasu zajmie Ci praca.
Więcej...
- O książce na temat planowania i pisania dokumentacji - część 1 i część 2
- Tu jest porównanie pisania dokumentacji do prania.
- Kilka tekstów na temat prostego pisania oraz Simplified Technical English (pierwszy, drugi).
- Tekst o tym, kim jest Subject Matter Expert.
- Tekst o pomocy dla Technical Writera.
W trakcie tworzenia...
- Wyrażaj się prosto i unikaj żargonu branżowego - dobra dokumentacja nie jest zrozumiała tylko dla zarozumiałych 😉 Jej funkcją jest rozwiewanie wątpliwości, a dzięki jej istnieniu i jakości dział obsługi klienta będzie mieć mniej roboty.
- Mniej znaczy więcej - nie rozwlekaj się. Eliminuj informacje, które nie są niezbędne. Wbrew pozorom ludzie nie lubią czytać 😉 a już na pewno nie lubią czytać dokumentacji.
- Jeśli przyjęta w Twoim środowisku strategia tworzenia dokumentacji na to pozwala, zwracaj się do odbiorcy bezpośrednio, ale bez nadmiernej familiarności. Używaj strony czynnej. Nie przypisuj przedmiotom, urządzeniom czy oprogramowaniu ludzkich cech i emocji.
- Jeśli tworzona przez Ciebie dokumentacja przyjęła formę tekstu, staraj się, aby było w nim dużo "światła" - akapitów, podpunktów, list numerowanych. Czytanie tzw. blachy tekstu jest męczące dla oczu i głowy.
Więcej...
- Style Guide w organizacji
- Dobra dokumentacja - cechy i etapy tworzenia
Przed publikacją...
- Czas na recenzję - nie bój się jej, to nie jest sąd kapturowy. Celem recenzji nie jest wytykanie Twoich błędów, ale ulepszenie dokumentacji i znalezienie wszystkich ewentualnych pomyłek.
- Sprawdź jeszcze raz, tym razem w docelowym formacie – niektóre błędy uparcie umykają uwadze wszystkich. Skorzystaj z pomocy kogoś, kto nigdy wcześniej nie widział Twojej dokumentacji ani nie ma pojęcia o Twojej dziedzinie zawodowej – świeże oko wnosi więcej niż się wydaje.
Więcej...
- Tekst na temat korekty i kilka słów o literówkach
- Tekst dla recenzenta
Koniec! Tworzenie dokumentacji to tylko tyle i aż tyle. A może chcecie coś dodać do powyższych punktów? Co waszym zdaniem jest najważniejsze, jakiej rady chcielibyście udzielić początkującym? Piszcie w komentarzach :-)