Dokumentacja oprogramowania to tylko zbiór artykułów. Ale nawet one mogą być frustrujące. Najpierw długo szukasz potrzebnej instrukcji. Potem zmagasz się z mało zrozumiałym tekstem. Robisz tak, jak jest napisane, a problem się nie rozwiązuje. Szukasz innego artykułu, denerwujesz się… Po godzinie poddajesz się i wychodzisz. Tak działa zła dokumentacja. Co sprawia, że jest taka, i jak to naprawić — czytaj dalej.
W naszej starej dokumentacji było wiele wad. Już prawie rok przerabiamy ją, aby opisany wyżej scenariusz nie odnosił się do naszych klientów. Zobacz, i .
Problem 1. Niezrozumiałe, źle napisane artykuły
Jeśli w dokumentacji nie można się połapać, jaki jest jej sens? Ale nikt celowo nie pisze niezrozumiałych artykułów. Powstają one, gdy autor nie myśli o odbiorcach i celu, lanie wody i nie sprawdzanie tekstu pod kątem błędów.
- Odbiorcy. Przed napisaniem artykułu należy pomyśleć o poziomie przygotowania czytelnika. Logicznym jest, że w artykule dla nowicjuszy nie należy pomijać podstawowych kroków i zostawiać terminów technicznych bez wyjaśnień, a w artykule o rzadkiej funkcji, potrzebnej tylko profesjonalistom, roztrząsać znaczenie słowa PHP.
- Cel. Jeszcze jedna rzecz, o której warto pomyśleć z wyprzedzeniem. Autor powinien postawić jasno określony cel, określić użyteczną akcję artykułu, zdecydować, co czytelnik zrobi po jego przeczytaniu. Jeśli tego nie zrobi, otrzyma opis dla samego opisu.
- Woda i błędy. Dużo niepotrzebnych informacji i biurokratyzmu, błędy i literówki przeszkadzają w percepcji. Nawet jeśli czytelnik nie jest perfekcjonistą, niedbałość w tekście może go odrzucić.
Uwzględnij wskazówki powyżej, a artykuły staną się bardziej zrozumiałe — to gwarantowane. Aby zrobić to jeszcze lepiej, skorzystaj z naszych .
Problem 2. Artykuły nie odpowiadają na wszystkie pytania
Źle, gdy dokumentacja nie nadąża za rozwojem, nie odpowiada na rzeczywiste pytania, a błędy w niej są niekorygowane przez lata. To problemy nie tylko autora, ale także organizacji procesów wewnętrznych firmy.
Dokumentacja nie nadąża za rozwojem
Funkcja już jest w wersji, marketing planuje ją promować, a okazuje się, że nowego artykułu lub tłumaczenia w dokumentacji wciąż nie ma. Z tego powodu musieliśmy nawet opóźnić wydanie. Można prosić wszystkich o terminowe przekazywanie zadań pisarzom technicznym, ale to nie zadziała. Jeśli procesu nie zautomatyzujemy, sytuacja będzie się powtarzać.
Wprowadziliśmy zmiany w YouTrack. Zadanie na napisanie artykułu o nowej funkcji trafia do pisarza technicznego w momencie, gdy zaczyna się testowanie. Wtedy też dowiaduje się o tym marketing, aby przygotować promocję. Powiadomienia trafiają również do korporacyjnego komunikatora Mattermost, więc niemożliwe jest przegapienie wiadomości od programistów.
Dokumentacja nie odzwierciedla potrzeb użytkowników
Przyzwyczailiśmy się pracować w ten sposób: funkcja wyszła, my o niej opowiadamy. Opisujemy, jak ją włączyć, wyłączyć i dostosować. Ale co, jeśli klient korzysta z naszego oprogramowania w sposób, którego nie zakładaliśmy? Albo napotyka błędy, o których nie pomyśleliśmy?
Aby dokumentacja była jak najbardziej kompletna, zalecamy analizę zgłoszeń do wsparcia, pytań na tematycznych forach i zapytań w wyszukiwarkach. Najpopularniejsze tematy przekazywać pisarzom technicznym, aby uzupełnili istniejące artykuły lub napisali nowe.
Dokumentacja się nie rozwija
Ciężko od razu zrobić wszystko idealnie, błędy i tak się pojawią. Można liczyć na opinie klientów, ale mało prawdopodobne jest, że zgłoszą każdą literówkę, niedokładność, niejasny lub nieznaleziony artykuł. Oprócz klientów dokumentację czytają też pracownicy, więc widzą te same błędy. Można to wykorzystać! Musimy tylko stworzyć warunki, w których łatwo będzie zgłosić problem.
Mamy grupę na wewnętrznym portalu, gdzie pracownicy zostawiają uwagi, propozycje i pomysły dotyczące dokumentacji. Wsparcie potrzebuje artykułu, a go nie ma? Tester zauważył niedokładność? Partner skarżył się menedżerom ds. rozwoju na błędy? Wszystko do tej grupy! Pisarze techniczni korygują coś od razu, coś przenoszą do YouTrack, coś biorą do przemyślenia. Aby temat nie osłabł, od czasu do czasu przypominamy o istnieniu grupy i ważności opinii zwrotnej.
Problem 3. Potrzebny artykuł trzeba długo szukać
Artykuł, którego nie można znaleźć, w niczym nie różni się od artykułu, którego nie ma. Hasłem dobrej dokumentacji powinna być fraza „Łatwo szukać, łatwo znaleźć”. Jak to osiągnąć?
Uporządkuj strukturę i określ zasady wyboru tematów. Struktura powinna być jak najbardziej przejrzysta, aby czytelnik nie musiał się zastanawiać „Gdzie mogę znaleźć ten artykuł?”. Reasumując, istnieją dwa podejścia: od interfejsu i od zadań.
- Od interfejsu. Zawartość duplikuje sekcje panelu. Tak było w starej dokumentacji ISPsystem.
- Od zadań. Tytuły artykułów i sekcji odzwierciedlają potrzeby użytkowników; w nagłówkach prawie zawsze znajdują się czasowniki oraz odpowiedzi na pytanie „jak to zrobić”. Teraz przechodzimy do takiego formatu.
Nie zależnie od wybranego podejścia, upewnij się, że temat odpowiada potrzebom użytkowników i jest przedstawiony w sposób, który pozwoli im rozwiązać swój problem.
Usprawnij centralne wyszukiwanie. W idealnym świecie wyszukiwanie powinno działać, nawet gdy popełnisz błąd lub pomylisz język. Nasza wyszukiwarka w Confluence na razie nie spełnia tych oczekiwań. Jeśli posiadasz wiele produktów, a dokumentacja jest wspólna, dostosuj wyszukiwanie do strony, na której znajduje się użytkownik. W naszym przypadku wyszukiwanie na stronie głównej działa dla wszystkich produktów, a jeśli jesteś już w konkretnej sekcji, to tylko dla artykułów w niej.
Dodaj spis treści i „okruszki chleba”. Dobrze, gdy na każdej stronie znajduje się menu i okruszki chleba — ścieżka użytkownika do bieżącej strony z możliwością powrotu na każdy poziom. W starej dokumentacji ISPsystem trzeba było opuścić artykuł, aby przejść do spisu treści. Było to niewygodne, dlatego w nowej to poprawiliśmy.
Umieść linki w produkcie. Jeśli użytkownicy ciągle zgłaszają podobne pytania do wsparcia, rozsądnie jest dodać przypomnienie z rozwiązaniem problemu w interfejsie. Jeśli masz dane lub zrozumienie, w którym momencie użytkownik napotyka problem, możesz także powiadomić go wiadomością e-mail. Zademonstrujesz troskę i odciążysz wsparcie.
Po prawej stronie w oknie dialogowym znajduje się link do artykułu o konfiguracji DNSSEC w sekcji zarządzania domenami ISPmanager
Skonfiguruj linki krzyżowe w dokumentacjiArtykuły, które są ze sobą powiązane, powinny być «ze sobą połączone». Jeśli artykuły tworzą sekwencję, koniecznie dodaj strzałki w przód i w tył na końcu każdego tekstu.
Prawdopodobnie najpierw poszukasz odpowiedzi na swoje pytanie nie u Ciebie, a w wyszukiwarce. To frustrujące, jeśli z przyczyn technicznych nie będzie linków do dokumentacji. Zadbaj zatem o optymalizację pod kątem wyszukiwarek.
Problem 4. Przestarzały układ utrudnia percepcję
Oprócz słabych tekstów, dokumentację może zepsuć design. Ludzie przyzwyczaili się do czytania dobrze skonstruowanych materiałów. Blogi, media społecznościowe, media — cały content jest podawany nie tylko w atrakcyjny, ale także łatwy do przeczytania sposób. Dlatego łatwo zrozumieć ból osoby, która widzi tekst jak na poniższym zrzucie ekranu.
W tym artykule zrzutów ekranu i wyróżnień jest tak wiele, że nie pomagają, a tylko utrudniają percepcję (grafika jest klikana)
Nie należy robić z dokumentacji długiego tekstu z masą efektów, ale podstawowe zasady trzeba uwzględnić.
Układ. Określ szerokość głównego tekstu, czcionkę, rozmiar, nagłówki i marginesy. Zaangażuj projektanta, a aby ocenić pracę lub poradzić sobie samodzielnie, przeczytaj książkę Artema Gorbunova «Typografia i układ». Przedstawia ona tylko jeden z wielu punktów widzenia na układ, ale jest wystarczająco dobra.
Wyróżnienia. Określ, co zasługuje na akcenty w tekście. Zwykle są to ścieżki w interfejsie, przyciski, fragmenty kodu, pliki konfiguracyjne, bloki „Zwróć uwagę”. Ustal, jak będą wyglądać wyróżnienia tych elementów i zapisz to w regulaminie. Pamiętaj, że im mniej wyróżnień, tym lepiej. Gdy jest ich dużo, tekst „szumi”. Hałas mogą tworzyć nawet cudzysłowy, jeśli są używane zbyt często.
Zrzuty ekranu. Ustal z zespołem, w jakich przypadkach potrzebne są zrzuty ekranu. Nie ma potrzeby ilustrowania każdego kroku. Duża liczba zrzutów ekranu, w tym pojedyncze przyciski, utrudnia percepcję i psuje układ. Określ rozmiar oraz format wyróżnień i podpisów na zrzutach ekranu i zapisz to w regulaminie. Pamiętaj, że ilustracje powinny zawsze odpowiadać pisaniu i być aktualne. Ponownie, jeśli produkt regularnie się aktualizuje, śledzenie każdego będzie trudne.
Długość tekstu. Unikajcie zbyt długich artykułów. Dzielcie je na części, a jeśli to niemożliwe, dodajcie na początku artykułu spis treści z linkami zakotwiczonymi. Prosty sposób na wizualne skrócenie artykułu — ukrycie szczegółów technicznych, potrzebnych wąskiemu gronu czytelników, pod spoilerem.
Formaty. Łączcie w artykułach różne formaty: tekst, wideo i obrazy. To poprawi odbiór.
Nie próbujcie zakrywać problemów ładnym formatowaniem. Szczerze, sami mieliśmy nadzieję, że 'opakowanie' uratuje przestarzałą dokumentację — nie udało się. W tekstach było tyle wizualnego szumu i zbędnych szczegółów, że regulamin i nowe formatowanie były bezsilne.
Wiele z powyższego będzie zależało od platformy, którą wykorzystujecie do dokumentacji. U nas na przykład jest to Confluence. Z nim też trzeba było się zmierzyć. Jeśli to interesujące, przeczytajcie opowieść naszego web dewelopera: .
Od czego zacząć poprawy i jak przetrwać
Jeśli wasza dokumentacja jest tak samo obszerna, jak u ISPsystem, a nie wiecie, za co się zabrać, zacznijcie od najpoważniejszych problemów. Klienci nie rozumieją dokumentacji — zajmijcie się poprawą tekstów, stwórzcie regulacje, przeszkolcie autorów. Dokumentacja jest nieaktualna — weźcie się za wewnętrzne procesy. Zacznijcie od najpopularniejszych artykułów o najbardziej poszukiwanych produktach: zapytajcie wsparcie, sprawdźcie analitykę strony i zapytania w wyszukiwarkach.
Mówiąc wprost — łatwo nie będzie. I szybko też raczej nie wyjdzie. Chyba że dopiero zaczynacie i od razu robicie to dobrze. Jedno wiemy na pewno — z czasem będzie lepiej. Ale proces nigdy się nie skończy :-).
Źródło: habr.com
