Podstawa pisania dobrej dokumentacji

Ten post został napisany przez gościa autora Jeffa Matsona. Jeff jest szefem dokumentacji GravityForms. Jest twórcą wtyczki Heartbeat Control WordPress i jest fanem lat 90-tych.

Często dokumentacja jest najbardziej niedocenianym elementem procesu rozwoju. Kiedy patrzymy na gwiazdy rocka w społeczności WordPressa, zazwyczaj patrzymy na programistów, projektantów i marketerów. Niewiele wiadomo o autorach dokumentacji, którzy przelewają krew, pot i łzy, aby wszystko przebiegało sprawnie.

Ten post dotyczy tych, którzy każdego dnia wpatrują się w niekończące się linijki kodu, aby rozszyfrować, co myśli programista, i prawdziwe znaczenie istniejącego kodu.

Dobra dokumentacja to więcej niż słowa

Dobrzy autorzy dokumentacji dostarczają więcej niż instrukcję obsługi, zapewniają doświadczenie. Znam doskonałych dokumentalistów, szkolonych początkujących, a największą różnicą między nimi jest zrozumienie mózgu tych, którzy to czytają. Podobnie jak powieść, dokumentacja ma przepływ, który utrzymuje zainteresowanie czytelnika i przyswaja więcej informacji, niż zdaje sobie sprawę.

Dokumentacja jakości jest skierowana do użytkowników, którzy z największym prawdopodobieństwem ją przeczytają. Stanowi również punkt odniesienia dla tych, którzy są mniej skłonni do jej przeczytania. Na przykład, jeśli dokumentujesz konkretny hak, zazwyczaj zakłada się, że programista będzie go czytał, ale co z tymi, którzy mają niewielkie doświadczenie w programowaniu?

Dobry autor dokumentacji zapewni punkt odniesienia dla tych, którzy potrzebują więcej nacisku we właściwym kierunku, bez konieczności kontaktowania się z pomocą techniczną, aby to dla nich wyjaśnić.

Dokumentacja ma większy wpływ niż myślisz

Większość po prostu ignoruje dokumentację, spychając ją w nieskończoną otchłań, aż nie będą mogli jej dłużej znieść. W niektórych przypadkach jestem winny tego samego. Ci ludzie nie zdają sobie sprawy, że za każdym razem, gdy ich wtyczka lub motyw pozostaje nieudokumentowany, cierpi na tym doświadczenie użytkownika.

Przyjrzyjmy się Twojemu najczęstszemu zgłoszeniu do pomocy technicznej. Gdybyś lepiej udokumentował ten problem, czy te bilety zniknęłyby całkowicie? Prawdopodobnie nie. Czy dostaniesz mniej zgłoszeń dotyczących problemu, a także zwiększysz produktywność siebie lub swojego agenta pomocy technicznej? Gwarantuję to. Myślę, że wszyscy moglibyśmy użyć mniejszej liczby zgłoszeń do pomocy technicznej.

Jak wspomniałem wcześniej, dokumentacja ma ogromny wpływ na wrażenia użytkownika. Jeśli użytkownik jest w stanie łatwo i sprawnie zlokalizować informacje, zaoszczędził swój i Twój czas. Średnia długość życia na świecie wynosi 66,57 lat, a Twoi użytkownicy woleliby robić ze swoim życiem coś innego niż bawić się kiepsko napisaną dokumentacją.

Jeśli klient zobaczy, że włożyłeś sporo czasu i wysiłku w twoją dokumentację, doceni cię, świadomie lub nie. Dobra dokumentacja pokazuje, że dbasz o nie po pierwszej sprzedaży.

Czy kiedykolwiek byłeś na haju po wydaniu ciężko zarobionych pieniędzy i wkrótce żałowałeś zakupu? Myślę, że wszyscy mamy. Dzięki odpowiedniej dokumentacji możesz uniknąć przekazywania tego uczucia swoim klientom.

Jak pisać lepszą dokumentację?

Pierwszym krokiem jest przestać tego unikać. Kiedy już jesteś w tym dobry, pisanie dokumentacji jest przyjemniejszym doświadczeniem, niż myślisz. W rzeczywistości stanie się drugą naturą. Tak jak wszystko inne na świecie, praktyka czyni mistrza.

Jednym z pierwszych kroków, które chcesz podjąć, decydując się na przeniesienie dokumentacji na wyższy poziom, jest określenie swoich problemów. W sprawie czego się z Tobą kontaktujesz? Jeśli zaczniesz pisać na ślepo o różnych rzeczach, może się okazać, że to, o czym piszesz, nie wywiera takiego wpływu, jaki byś chciał.

Jedną z najlepszych technik, jakie odkryłem, jest śledzenie liczby biletów, które są udokumentowane w porównaniu z tymi, które nie są, i dzielenie tych, które nie są na kategorie. W ten sposób możesz lepiej ukierunkować swoje punkty bólu i poprawić części, które mogą nie być tak pomocne, jak powinny.

Po ustaleniu, jaką dokumentację należy napisać, należy określić grupę docelową i podzielić ją na programistów, użytkowników i użytkowników zaawansowanych. Pomaga to zaspokoić tę konkretną publiczność. Nieco później omówimy, jak kierować reklamy na tych użytkowników.

Następnie chcesz podzielić dokument. Deweloperzy powinni podzielić to na surowe informacje (zaakceptowane argumenty, wartości zwracane itp.), konkretne przykłady i przypadki użycia. Dla użytkowników najlepszym sposobem postępowania jest przewodnik. Każdy krok, który będą musieli podjąć, bez względu na to, jak trywialny może się wydawać, jest krytyczny.

Przemawiaj do nich na każdym kroku. Dokumentacja dla zaawansowanych użytkowników jest bardzo podobna do scenariusza użytkownika, ale jest bardziej ustrukturyzowana i możliwa do skanowania. Bądź jasny, ale pozwól im łatwo przeskoczyć do miejsca, w którym muszą się udać, bez wcześniejszego czytania poprzedniego kroku.

Sztuka pisania lepszej dokumentacji

Jeśli chodzi o sztukę pisania dokumentacji, pisz w sposób, który najlepiej trafia do odbiorców, ale także używaj prostego języka, o którym wiesz, że zrozumieją. Jednym z najlepszych powodów są tłumaczenia. Chociaż tłumaczenie Google wykonuje świetną robotę, o wiele łatwiej jest przetłumaczyć proste słownictwo 5-klasisty niż to zawarte w pracy podyplomowej.

W swoich treściach nie bój się umieszczać linków do odpowiednich treści. Pozwoli to uniknąć powtarzania się w wielu dokumentach, a czytelnikowi cofnie się, jeśli potrzebuje więcej informacji na dany temat. W końcu Twoim głównym celem jest uszczęśliwienie użytkownika i zaoszczędzenie czasu.

Proces tworzenia dokumentacji nie zatrzymuje się po naciśnięciu przycisku publikowania . Wróć i popraw każdy dokument w razie potrzeby. Niemal natychmiast po opublikowaniu dokumentu wróć i sprawdź, czy śledzone bilety pomocy technicznej zostały odrzucone, a ruch do tego konkretnego artykułu wzrósł. Zwykle pomaga to, gdy dany artykuł generuje większy ruch. Jeśli uzyskujesz większy ruch, ale taką samą liczbę zgłoszeń do pomocy technicznej, możesz zajrzeć do tego artykułu, aby dowiedzieć się, dlaczego.

Czego się nauczyliśmy

Po pierwsze, mam nadzieję, że po zajściu tak daleko, lepiej docenisz tych, którzy są w okopach, pisząc dokumentację, którą większość z nas uważa za pewnik. To naprawdę jest forma sztuki, którą wielu z nas, którzy tworzą dokumentację życiową, naprawdę cieszy się i poświęca wiele, wiele godzin.

Mam również nadzieję, że odchodzisz od tego artykułu, myśląc więcej o istniejącej dokumentacji i o tym, jak można ją ulepszyć. Właściwa dokumentacja może być niezwykle satysfakcjonująca, a pisanie w praktyce może być całkiem zabawne.

Dokumentuj wcześnie, dokumentuj często. Świetny produkt to coś więcej niż świetny kod, jest też pięknie udokumentowany.