Jakiego stylu dokumentacji powinni używać menedżerowie produktu, aby przekazać odpowiedni komunikat?

*Dokumentacja jest jednym z najważniejszych i najbardziej niedocenianych elementów każdego projektu open-source i nie należy jej lekceważyć.

Ogólnie rzecz biorąc, większość projektów open source nie otrzymuje odpowiedniej uwagi po prostu dlatego, że ich autorzy nie są tak naprawdę zainteresowani, nie są w stanie lub nie mają czasu na stworzenie skutecznego środowiska dokumentacyjnego dla ich API i dokumentacji produktu.

Chociaż twoja aplikacja może być doskonała, jeśli dokumentacja jest nieodpowiednia, konsumenci nie będą w stanie czerpać korzyści z jej użytkowania.

Jednak nawet jeśli nie będą mieli innego wyjścia, jak tylko wykorzystać ją z jakiegokolwiek powodu, nie będą w stanie zrobić tego z powodzeniem lub w sposób, w jaki byś tego chciał.

Zrozumienie, jak tworzyć doskonałą dokumentację, wymaga znacznej ilości pracy, podobnie jak okresowe przeglądanie innych projektów dokumentacyjnych. Ale uwierz mi na słowo - jako ktoś, kto stworzył mnóstwo dokumentacji dla Docsie - jeśli tworzysz kod, który będzie używany przez kogoś innego niż ty, a zwłaszcza jeśli te osoby są twoimi klientami, twój produkt powinien być dobrze udokumentowany, sformatowany i dynamicznie prezentowany.

Jeśli chodzi o samouczki, instrukcje, wyjaśnienia i referencje, jaka jest różnica?

Wiele osób błędnie uważa, że te cztery wyrażenia odnoszą się do tego samego elementu. Wyrażają one jednak wiele różnych znaczeń. Te różne rodzaje dokumentacji są dość istotne i mają pewne kluczowe różnice:

Dokumentacja samouczków: Te rodzaje dokumentacji są dokumentacją opartą na informacjach, zorientowaną na szkolenia.

Dokumentacja poradników/przewodników użytkownika: Przewodniki użytkownika dokumentują, jak rozwiązać konkretne problemy poprzez serię kroków, aby osiągnąć określony cel.

Dokumentacja objaśniająca: Jest to dokumentacja typu artykuł, która ma pomóc użytkownikowi/czytelnikowi uzyskać głębsze zrozumienie produktu poprzez różne wyjaśnienia i kontekst.

Dokumentacja referencyjna: Dokumentacja ta ma na celu poinformowanie użytkownika o opisie różnych nowych aktualizacji funkcji i zastosowań. Ten rodzaj dokumentacji może być bardzo "surowy" w formie dokumentacji deweloperskiej, jednak można je również przetłumaczyć na bardziej przyjazne dla użytkownika noty wydania, które mogą być łatwo zrozumiane przez użytkownika końcowego.

Powody tworzenia wysokiej jakości dokumentacji

Zanim przejdziemy dalej, kluczowe jest zrozumienie, dlaczego kompetentne pisanie dokumentacji jest bardzo ważną, ale niedocenianą potrzebą w dzisiejszym społeczeństwie. Dostępność obszernej i dobrze napisanej dokumentacji jest jednym z najważniejszych kryteriów osiągnięcia powszechnej adopcji, szczególnie w projektach open source, w których praktycznie każde działanie jest dostępne publicznie i gdzie takie działania odgrywają kluczową rolę w sukcesie projektu.

Przyjrzyjmy się najważniejszym powodom, dla których warto pisać skuteczną dokumentację.

Pozwala stworzyć lepsze doświadczenie onboardingowe dla klientów.

Dostarczając klientom odpowiednią dokumentację dotyczącą produktu, pomagasz im, sprawiając, że czują się bardziej komfortowo z produktem i są chronieni przez jego konkretne wytyczne. Aby tak się stało, należy wykonać następujące czynności:

1. Upewnić się, że dokumentacja produktu jest widoczna i łatwo dostępna, za pośrednictwem linków w aplikacji lub na platformie dokumentacji z możliwością wyszukiwania.

2. Upewnij się, że są one dobrze napisane i pomagają klientowi w szybkim i łatwym znalezieniu odpowiedzi

Jedną z rad jest napisanie dokumentacji tylko raz, a będzie ona wielokrotnie analizowana, gdy firma pozyska nowych klientów.

W konsekwencji będzie mniej zapytań o wsparcie.

Klienci, którzy czytają i rozumieją Twoją dokumentację, są bardziej skłonni do zakupu Twoich produktów. Kiedy klienci nie są w stanie niczego rozgryźć, może to być dość irytujące i zamiast tego mogą zacząć obwiniać twój produkt.

Niektórzy klienci mogą natychmiast skontaktować się lub wysłać e-mail do personelu pomocy technicznej, jeśli napotkają przeszkodę; ale jeśli dokumentacja jest atrakcyjna, łatwo dostępna i zrozumiała, będą w stanie rozwiązać własne problemy bez konieczności konsultowania się z tobą, co z kolei sprawi, że poczują się bardziej upoważnieni.

Pomaga wspierać własny zespół.

Solidna baza wiedzy może być również wykorzystywana do pomocy członkom własnego zespołu. Twój wewnętrzny zespół powinien być informowany o nowych funkcjach, planowanych planach działania, dokumentacji API i wszystkim innym, co jest niezbędne, aby wszyscy byli na tej samej stronie.

Instrukcje krok po kroku dotyczące pisania skutecznej dokumentacji

Pisanie treści dokumentu i organizowanie tego działania to dwa zupełnie różne zadania od określenia, jakiego tonu użyć i jak zapewnić, że dokumentacja jest zrozumiała. Jak stwierdził O'Reilly, istnieje 8 zasad doskonałej dokumentacji:

1. Twórz dokumentację, która jest zachęcająca dla czytelnika.

2. **Tworzenie dokładnej dokumentacji obejmującej wszystkie obszary projektu.

3. **Tworzenie łatwych do zrozumienia materiałów.

4. **Tworzenie dokumentacji, która demonstruje, jak korzystać z produktu poprzez studia przypadków.

5. **Tworzenie dokumentacji zawierającej powtórzenia tam, gdzie jest to konieczne.

6. Pisz dokumentację, która jest aktualna.

7. Pisz dokumentację, która jest łatwa do współtworzenia

8. Pisz dokumentację, która jest łatwa do odkrycia i zrozumienia.

Elementy te dotyczą głównie treści. Następnie przejdziemy do "jak" strukturyzowania tych informacji w sześciu krokach:

Podejmij decyzję o tym, co powinieneś nagrać.

Poświęć trochę czasu na zastanowienie się, jaki rodzaj dokumentacji będziesz tworzyć przed rozpoczęciem: czy jest to samouczek, dokument referencyjny, instrukcja obsługi czy wyjaśnienie?

Należy pamiętać, że charakter produktu będzie miał bezpośredni wpływ na rodzaj dokumentacji, za której stworzenie będziemy odpowiedzialni.

Stwórz strukturę.

Najpierw zbuduj fundament dla swojej dokumentacji. Na początku może to być coś bardzo małego i może obejmować tylko kilka grup, ale z czasem cała platforma, na której budujesz, zacznie rosnąć pod względem wielkości i złożoności. Powinieneś regularnie przeglądać swoją strukturę organizacyjną.

Pamiętaj, że jesteś instruktorem i jesteś ostatecznie odpowiedzialny za to, jak uczniowie uczą się w twojej klasie. Będą oni kierować się twoimi wskazówkami; dlatego im więcej czasu poświęcisz na strukturę, tym większe sukcesy odniosą twoi uczniowie.

Zawsze korzystaj z solidnych technik multimedialnych.

Upewnij się, że korzystasz z filmów, rysunków i różnych stylów i podłączasz je bezpośrednio do swojej dokumentacji. Docsie umożliwia osadzanie dowolnych z nich na naszej platformie, aby ułatwić ten proces.

Nie tylko pomogą one konsumentom w lepszym zrozumieniu wyrażanych informacji, ale także zapewnią fantastyczną optymalizację pod kątem wyszukiwarek, co doprowadzi do większej liczby wysokiej jakości potencjalnych klientów w wyniku dynamicznej dokumentacji.

Upewnij się, że można ją przeszukiwać.

Istnieją różnice w możliwościach wyszukiwania na różnych platformach baz wiedzy - niektóre z nich oferują tylko podstawowe wyszukiwanie bez możliwości zagłębiania się w segmentacje (co jest technicznie w porządku, jeśli nie masz tysięcy plików), podczas gdy inne oferują opcje zapytań, które pozwalają wyszukiwać nie tylko w dokumentach, ale także w nazwach użytkowników.

Jest jednak jedna rzecz, która ma kluczowe znaczenie: powinieneś korzystać z narzędzia, które pozwala na szybkie wyszukiwanie. Funkcja wyszukiwania zawarta w aplikacji ułatwia wyszukiwanie plików i uzyskiwanie ich podglądu bez opuszczania aplikacji.

Docsie pozwala na dynamiczne przeszukiwanie nawigacji w celu uzyskania łatwo dostępnych informacji.

Ciągłe dążenie do poprawy i aktualizacji

Tworzenie i korzystanie z dokumentów jest trudne, ponieważ są one szybko zapominane przez osoby, które je wygenerowały lub czerpały z nich korzyści. Dokumenty napotykają również wiele wyzwań na swojej drodze.

W miarę upływu czasu struktura folderów przybiera wygląd cmentarza, ponieważ starsza dokumentacja ma tendencję do pozostawania na niższej pozycji na ekranie monitora.

Pamiętaj więc, aby wrócić do swojej starej dokumentacji i wprowadzić ulepszenia, a także zachęcać swoich współpracowników do robienia tego samego od czasu do czasu. Docsie pozwala na tworzenie aktualizacji poprzez nasz zaawansowany system wersjonowania, który jest prosty i łatwy do wykonania.

Końcowe przemyślenia:

Chcesz dowiedzieć się więcej o tym, jak pisać skuteczną dokumentację? Profesjonaliści zajmujący się dokumentacją oprogramowania mogą znaleźć mnóstwo blogów i informacji tutaj.