Dokumentacja techniczna

Dokumentacja pisana z produktu, a nie ze specyfikacji

Większość złej dokumentacji powstała na podstawie dokumentu z wymaganiami lub pamięci programisty. Opisuje, jak funkcja miała działać, a nie ekran, który użytkownik faktycznie widzi, z przemianowanym przyciskiem i dodatkowym krokiem potwierdzenia. Użytkownik wykonuje krok czwarty, nie znajduje niczego pasującego i otwiera zgłoszenie.

Każdą procedurę w produkcie wykonujemy przed jej opisaniem, na koncie testowym, w roli, którą będzie mieć czytelnik. Gdy krok działa inaczej, niż zespół się spodziewa, odnotowujemy to, bo praca nad dokumentacją rutynowo ujawnia błędy, których nikt nie zgłosił. Ta lista często okazuje się równie cenna jak sama dokumentacja.

Oddziel zadanie od wyjaśnienia

Użytkownik, który chce wyeksportować fakturę, nie chce najpierw trzech akapitów o modelu rozliczeń. Użytkownik, który chce zrozumieć model rozliczeń, nie chce numerowanej listy kliknięć. Mieszanie obu w jednym artykule utrudnia znalezienie i spowalnia czytanie.

Dzielimy treści na zadania (jak zrobić jedną rzecz), pojęcia (jak coś działa i dlaczego) oraz materiały referencyjne (ustawienia, pola, limity, kody błędów). Każdy typ ma własny szablon, więc strony pozostają spójne po przekazaniu, gdy Państwa zespół doda czterdziesty artykuł.

To lista terminów utrzymuje spójność całości w czasie. Jeśli interfejs mówi „workspace”, dokumentacja nigdy nie nazywa tej samej rzeczy „project” ani „account”. To niewielki dokument, który zapobiega większości zgłaszanych przez użytkowników nieporozumień.

• Artykuły zadaniowe: jeden cel, numerowane kroki, wynik, który użytkownik powinien zobaczyć
• Artykuły pojęciowe: model stojący za funkcją, z diagramem, gdy pomaga
• Strony referencyjne: każde pole, ustawienie i limit, w przejrzystej tabeli
• Rozwiązywanie problemów: komunikat błędu w brzmieniu, jego przyczyna i rozwiązanie