Nadszedł czas, żeby zabrać się za zawartość przesyłki, którą opisywaliśmy w poprzednim wpisie z cyklu "Naucz się sam(a)". Zaczynamy od książki "Technical Writing 101: A Real-World Guide to Planning and Writing Technical Documentation" autorstwa Alana S. Pringle i Sarah S. O'Keefe.
Książka jest dobrym wprowadzeniem w dziedzinę Technical Writingu. Pomimo tego, że zawiera w sobie sporo podstawowych informacji, to według nas nie jest przeznaczona tylko i wyłącznie dla osób stawiających pierwsze kroki w pisaniu dokumentacji. Dla nowicjuszy jest to świetne i łagodne wprowadzenie w branżę, a dla bardziej doświadczonych dokumentalistów jest to dobre uzupełnienie braków w podstawach oraz sprawdzenie czy przyjęte przez nich zasady są właściwe. Tym bardziej zachęcamy do lektury, że w naszym kraju edukacja formalna w dziedzinie Technical Writingu praktycznie nie istnieje, o czy już wspominaliśmy kilkukrotnie. Dlatego też, wiele osób piszących dokumentację swoją wiedzę budowało we własnym zakresie, czy to ucząc się od bardziej doświadczonych kolegów i koleżanek, czy starą dobrą metodą prób i błędów.
Naszym celem nie jest napisanie dokładnej recenzji książki, tylko przekazanie dalej w skondensowanej formie informacji, które mogą okazać się przydatne w poruszaniu się w świecie Technical Writingu. Wszelkie podane niżej wytyczne są zaczerpnięte wprost z książki i w żadnym wypadku nie są to nasze złote myśli. To tak gwoli ścisłości 😊 Książka liczy ponad 200 stron, dlatego też żeby Was nie zanudzić, informacje podzieliliśmy na dwa wpisy. Życzymy przyjemnej lektury.
Kim jest Technical Writer?
-
To tak naprawdę tłumacz, ponieważ dostaje w ręce jakąś skomplikowaną technologię i jego misją jest wytłumaczenie osobom, które nie znają tej technologii, jak jej używać.
-
Technical Writer powinien odznaczać się następującymi cechami:
- Znajomość technologii - nie trzeba być specjalistą, ale niezbędne jest podstawowe zrozumienie technologii, o której piszemy. Niewiedza na temat jakiegoś rozwiązania też może być pomocna, ponieważ wtedy działamy jak użytkownicy, którzy nie znają produktu i dzięki temu widzimy z czym mogą mieć największe problemy. Jednak nie możemy stosować tej strategii, żeby usprawiedliwiać swoją niechęć do zdobywania nowej wiedzy.
- Umiejętność pisania - jest to inny rodzaj pisania od tego, który znamy ze szkolnych wypracowań. Głównym celem jest przekazanie użytkownikowi jasnej informacji. Ważny jest również odbiorca docelowy, ponieważ do niego należy dostosować język jakiego używamy.
- Zdolności organizacyjne - umiejętność organizowania treści w dokumencie, ale także umiejętność zarządzania czasem i projektami.
- Zdolności detektywistyczne i umiejętność pracy z ludźmi - w przeciwieństwie do autorów powieści, Technical Writer nie może wymyślać informacji na podstawie, których pisze instrukcje. Musi je wyszukać w dostępnych źródłach lub zdobyć od współpracowników, stąd ważne jest, żeby wiedzieć jak szukać informacji i jak rozmawiać z ludźmi. Ważna jest też zdolność odpowiedniego filtrowania zdobytej wiedzy.
Jak wygląda proces tworzenia dokumentacji?
Cały proces można podzielić na następujące kroki:
- Określenie dokumentów, które mają zostać dostarczone.
- Stworzenie zarysu każdego dokumentu.
- Stworzenie planu dla całego projektu z rozbiciem na zadania i terminy.
- Tworzenie treści.
- Stworzenie lub zdobycie szablonów.
- Edycja informacji oraz sprawdzenie stworzonych dokumentów przez innego Technical Writera lub redaktora.
- Przegląd dokumentów przez eksperta w kwestiach merytorycznych.
- Stworzenie indeksu.
- Wyprodukowanie dokumentacji w docelowym formacie.
Powyższy podział to tylko teoria. W praktyce produkt będzie się zmieniał w trakcie pisania dokumentacji, więc czasami będąc na kroku 7 trzeba będzie się cofnąć do kroku 4. Autorzy zaznaczają, że z własnego doświadczenia wiedzą, że takie sytuacje wystąpią na pewno, więc najlepiej od razu psychicznie się na nie przygotować.
Jak planować dokumentację?
-
Planowanie dokumentacji jest bardzo istotne, pomimo tego, że często jest to "wróżenie z fusów".
-
Zazwyczaj szacunki dotyczące ilości pracy są bardzo rozbieżne z rzeczywistością, dlatego po wykonaniu pracy należy spojrzeć wstecz i ocenić jak bardzo szacunki były mylne i ustalić co wpłynęło na te rozbieżności. Dzięki temu następnym razem nasze szacunki będą dokładniejsze.
-
Society for Technical Communication (STC) proponuje taki przelicznik:
- Kompletna strona (pisanie, edycja, indeksowanie, projektowanie szablonu i formatowanie dokumentu, produkcja) = 8 godzin pracy
- Rozdział pomocy online = 8 godzin pracy
- Instrukcja przewidziana na 1 godzinę = 40 godzin pracy
Skąd czerpać informacje do dokumentacji?
-
Specyfikacje techniczne:
- Redukują czas potrzebny na rozmowy z ekspertami
- Zazwyczaj są niedokładne lub w ogóle ich nie ma. Dokładna i pełna specyfikacja jest jak Yeti, ktoś kiedyś ją widział, ale nie wiadomo czy na pewno
-
Prototypy i rozwijane oprogramowanie:
- Dają namiastkę tego jak będzie wyglądał produkt
- Ciągle się zmieniają i są niekompletne. Dla użytkowników produkt to interfejs graficzny. Nie za bardzo interesuje ich co się dzieje "pod spodem", tylko jak to obsługiwać. Dla osób tworzących oprogramowanie nie jest to oczywiste, więc często nie zdają sobie sprawy, że jedna, według nich mała, zmiana interfejsu oznacza spore zmiany w dokumentacji. Dlatego dodanie zrzutów ekranu najlepiej odwlec w czasie ile się da, żeby nie robić tego kilka razy.
-
Poprzednie wersje dokumentacji:
- Jeśli są dobrze napisane, mogą posłużyć jako baza dla nowej wersji co zaoszczędzi nam sporo czasu
- Jeśli są kiepsko napisane ich poprawa może być bardziej czasochłonna niż napisanie dokumentów od początku
-
Deweloperzy i eksperci w kwestiach merytorycznych (Subject Matter Experts):
- Najlepsze źródło informacji
- Często nie mają czasu na dokumentację albo podchodzą do niej jak do zła koniecznego i się nie przykładają
-
Rozmowy z użytkownikami:
- Informacja z pierwszej ręki jak produkt jest używany
- Rzadko kiedy jest na to czas i/lub fundusze
Jak pisać?
-
Zawsze pamiętaj dla kogo piszesz - dostosuj informacje do poziomu wiedzy grupy docelowej, np. nie pisz o tym jak włączyć przeglądarkę w dokumencie dla programistów.
-
Pisz językiem na poziomie uczniów ósmej klasy według amerykańskiego systemu szkolnictwa (eight grade), czyli uczniów w wieku 12-14 lat:
- Używaj jasnych zdań twierdzących
- Unikaj żargonu, slangu i idiomów
- Jeśli musisz użyć skomplikowanych terminów i akronimów, wyjaśnij je
- Używaj nagłówków, paragrafów, wypunktowań w celu podziału dokumentu na kawałki, które są "do przejścia"
-
Nie używaj języka nacechowanego płciowo chyba, że dokument jest skierowany wyłącznie do kobiet lub mężczyzn.
-
Zmiany w harmonogramie tworzenia dokumentacji są tak pewne jak podatki i śmierć - rzadko kiedy wszystko idzie w pełni zgodnie z planem.
Jak tworzyć instrukcje opisujące wykonywanie konkretnych zadań?
- Nie opisuj funkcji dostępnych w interfejsie użytkownika w kolejności w jakiej występują, tylko w takiej jaką wybrałby użytkownik.
- Opisując jakąś czynność warto dodać co się stanie po jej wykonaniu. Wynik jakiejś czynności nie powinien być kolejnym numerowanym krokiem. Można podać go w nowej linijce dla wyróżnienia.
- List numerowanych używaj dla czynności, które powinny zostać wykonane w określonej kolejności.
- List wypunktowanych używaj dla czynności, które nie muszą zostać wykonane w określonej kolejności.
- Używaj list wypunktowanych dla sekwencji trzech lub więcej elementów, zamiast wymieniać je w pojedynczym zdaniu.
- Zanim przedstawisz kroki potrzebne do wykonania jakiejś czynności, napisz zdanie lub dwa wstępu do czego ona prowadzi.
- Nie nadużywaj ostrzeżeń, ponieważ użytkownik przestanie zwracać na nie uwagę.
Edycja dokumentu przed publikacją
-
Autorzy z własnego doświadczenia podają, że osoba edytująca dokumentację przed publikacją jest w stanie przejść przez 10 stron w ciągu godziny, co daje 400 stron na tydzień.
-
Poniżej znajduje się lista cech dobrego dokumentu. Jeśli musimy poświęcić którąś z tych cech z powodu napiętych terminów, powinniśmy zacząć od ostatniej pozycji i iść w górę:
- Dokładność pod względem technicznym - dokument musi opisywać produkt w sposób rzetelny. Lepiej napisać dokładną instrukcję, która ma literówki niż niedokładną, która jest wzorem poprawnej pisowni.
- Kompletność - dokument opisuje wszystkie funkcje produktu lub tyle ile się da.
- Organizacja - treść jest uporządkowana logicznie.
- Indeks - ponieważ użytkownik zazwyczaj zaczyna czytanie dokumentu od indeksu, posiadanie indeksu jest ważne, ale nie aż tak jak dokładność pod względem technicznym.
- Gramatyka i pisownia - poprawienie błędów pisowni i gramatycznych jest niezbędne do prawidłowej komunikacji, ale jest to mniej ważne od dokładności pod względem technicznym
- Trzymanie się przewodnika stylu - sprawia, że dokumenty są bardziej spójne, jednak wytłuszczenie wszystkich nazw menu powinno być ostatnim zmartwieniem kiedy terminy są napięte.
- Przygotowanie do druku - czyli sprawdzenie czy dokument nadaje się do publikacji (podziały wierszy i stron, nagłówki, stopki, itd.). Ten proces sprawia, że dokument wygląda profesjonalnie, ale nie zastąpi on opisu produktu.
Pomimo tego, że niektóre elementy na liście są ważniejsze od innych, nie oznacza to, że te mniej ważne można zawsze pominąć. Jeśli ciągle musisz poświęcać któryś z elementów, to wygląda na to, że masz za mało czasu na pisanie dobrej dokumentacji. W takiej sytuacji porusz tą kwestię z przełożonym.
Na tym kończymy dzisiejszy wpis. Część druga już niebawem. Stay tuned 😊