Jak pisać zwięzłe dokumentacje?
Przedstawię Ci wskazówki jak zrobić aby Twoja dokumentacja była zwięzła i treściwa. Opis techniczny czy biznesowy? Jak to połączyć?
ZANIM napiszesz pierwszy wyraz dokumentacji to…
1. OKREŚL KTO GO BĘDZIE CZYTAŁ
Wiele osób zapomina o tym, że dokumentacje będą czytały konkretne osoby. Nam zależy na tym, żeby te konkretne osoby zrozumiały to co im chcemy przekazać za pomocą dokumentacji.
Inaczej więc będziemy pisać jeśli odbiorcą będzie Techniczny Kierownik Projektu po stronie klienta. W inny sposób będziemy pisać gdy dokumentacje „odbiera” Prezes firmy, który ma osobowość sprzedawcy i bardziej zwraca uwagę na aspekty wizualne niż techniczne.
Prawdziwa trudność jest jednak gdy tekst musi być pisany pod osobowość z kompetencjami „biznesowymi” i „technicznymi”. Wtedy ilość detali, którą trzeba zawrzeć jest większa. Nie będę cię czarował – taki „case” występuje najczęściej. Wiele osób piszących dokumentacje w takim przypadku zastanawia się:
jak opisać rzeczy funkcjonalne i techniczne w dokumentacji aby było zrozumiale? Czy pisać to w jednym akapicie? Czy rozdzielić na dwa? A może zrobić dwa dokumenty – jeden techniczny, drugi „biznesowo-funkcjonalny”.
Temat nie jest trywialny bo jest strategiczny. Musisz uwzględnić również elementy utrzymania swojej dokumentacji podejmując taką decyzję. Najważniejszą rzeczą będzie na tym etapie „wczucie” się w osobę czytającą i próba pisania pod konkretnego Pawła, Marka czy Kasię.
FYI: w kursie Dokumentacja.Pro zdradzam dużo tipów jak to robić dobrze.
Jeśli określiłeś już odbiorcę i dobrałeś odpowiednią strategię pisania to…
Wiedza o Dokumentacji IT na twój adres e-mail?
2. NAPISZ SPIS TREŚCI
Jest to jedna z ważniejszych rzeczy. Nie zrozum „spisu treści” zbyt płytko – mam tutaj na myśli całą strukturę dokumentu. Jeśli zaprojektujesz spis treści źle to zrozumienie dokumentacji będzie również słabe.
Powiem Ci jak wygląda „dynamika” skupienia uwagi odbiorcy. Zazwyczaj gdy zaczyna się czytać dokument to jesteśmy bardzo skupieni. Wtedy zazwyczaj będziemy dawać komentarze i uwagi do rzeczy nawet mało istotnych. Wraz z upływem czytanego tekstu (czasami nawet po jednej stronie) nasze skupienie spada. Spada tym szybciej im mniej rozumiemy tekst.
W praktyce wygląda to tak, że gdy odbiorca czyta „środek” dokumentu, gdzie zazwyczaj są najważniejsze rzeczy to jego uwaga jest minimalna. Bo przez złą strukturę tekstu (zły spis treści) rozumie mało z tego co czyta. Więc najważniejsze detale umykają jego uwadzę.
Zazwyczaj jest tak, że na koniec dokumentu „budzimy się” i nasze skupienie wzrasta. Z tego powodu, że chcemy mieć na koniec poczucie, że „przerobiliśmy tekst w skupieniu”. Co oczywiście jest tylko pozorne. Najwięcej uwag do dokumentacji jest więc na początku i na końcu.
Nie jesteś w stanie wpłynąć na to czy twój odbiorca przeczyta dokumentację czy nie (bo zdarza się również, że klient akceptuje bez czytania i bez zrozumienia), ale to co możesz zrobić to:
utrzymać uwagę odbiorcy jak najdłużej i napisać tekst maksymalnie zrozumiale dla czytającego.
Niestety na nic więcej nie masz wpływu – pogódź się z tym. Aby utrzymać uwagę odbiorcy i uzyskać maksymalne zrozumienie kluczową rolę odgrywa właśnie DOBRY spis treści. Czyli dobra struktura dokumentu. Jeśli zrobisz ją źle – dokument będzie niezrozumiały dla czytającego. Wtedy masz sytuację jakbyś go nie napisał wcale.
Jeśli chcesz sam się szkolić z tego tematu to poczytaj o heurystykach podziału dokumentacji, o dziedzinie projektowej i kontekstach. Ja w kursie zrobiłem aż dwie lekcje o spisie treści, strukturze dokumentu – więc zapraszam po wiedzę w pigułce do kursu wyjaśnię Ci to w kilkanaście minut 🙂
Jeśli już masz spis treści i zrobiłeś opisy w dokumentacji…
OBGRYŹ TEKST DO KOŚCI
Brzmi przerażająco, ale takie nie jest 🙂 Chodzi o to aby twój tekst dobrze się czytało.
Musisz pamiętać, że dokumentacja jest tekstem klasyfikowanym jako techniczny. Używa się w niej zwrotów, których nie użył byś podczas „mówienia”. I odwrotnie… nie powinieneś używać zwrotów potocznych i „mówionych” w swojej dokumentacji. Mimo, że wydaje się to oczywiste, często spotykam takie określenia w dokumentacji jak:
Zrobię aplikację, która będzie działała przy dość dużym ruchu.
Nie muszę pisać, że powyższe zdanie jest błędne. Zadanie na spostrzegawczość dla Ciebie – wypisz mi ile błędów „analitycznych” widzisz w tym zdaniu 🙂 Napisany przez Ciebie tekst powinien być jednoznaczny. I obgryziony do kości… czyli taki, że po wyrzuceniu jakiegokolwiek wyrazu zdanie traci sens. Nie używaj więc proszę ozdobników mowy podczas pisania.
„Keep it simple as fuck”, ale nie tracąc jednoznaczności.
Tutaj błędów, które możesz popełnić jest dużo więcej, ale tymi wskazówkami chciałem Ci nakreślić odpowiedni „mindset” jaki powinieneś mieć podczas pisania tekstu do dokumentacji.
Największe błędy jakie możesz popełnić podczas pisania to:
- używanie skrótów myślowych – „skróty” powinieneś wyodrębnić do słowniczka dokumentacji, a zdania pisać pełne i jednoznaczne;
- nie obgryzanie tekstu do kości – czyli różnego rodzaju „ozdobniki” w stylu: „Tutaj mamy widok aplikacji, a skoro użytkownik ma rangę administratora to widzi również dodatkowy przycisk” (to zdanie jest błędne). Należy je obgryźć do kości;
- użycie złej „osoby” podczas pisania / złych zwrotów – trudno czyta się dokumentację, gdy jest napisana w niepoprawnej formie.
- Brak jednoznaczności tekstu – czyli różnego rodzaje sytuacje, gdzie tekst można zrozumieć dwojako, lub trojako.
Temat (jak poprzednie) do najłatwiejszych nie należy. Ale łatwych tematów nie warto poruszać 🙂
Jeśli więc rzeczy, które opisywałem mają dla Ciebie sens to zapraszam Cię do udziału w moim kursie – Dokumentacja.Pro, gdzie przeprowadzę Cię z punktu A, do punktu B gdzie:
Punkt A – mamy „zlecenie” na napisanie dokumentacji. Musimy spotkać się z klientem i dowiedzieć się od niego „co ma być zrobione”.
Punktu B – masz napisaną zrozumiałą dokumentację z niezbędnymi diagramami. Proces pisania przebiegł efektywnie – pokazuję Ci jak współpracować z klientem i programistami podczas pisania dokumentacji. Mając napisany tekst uzyskujesz maksymalną satysfakcję klienta ze zrealizowanego projektu. Napisana dokumentacja jest „gotowa” do realizacji przez programistów. Nie potrzebne są dodatkowe wysiłki by zlecić pracę.
Tymczasem jeśli masz jakieś pytania dotyczące tworzenia dokumentacji – zadaj je w komentazu. Postaram Ci się pomóc 🙂
Dziękuję, że przeczytałeś ❤️
Pssst... przygotowałem dla Ciebie kilka prezentów - wybierz co Ci się przyda! 👍
