Jak pisać dokumentację techniczną

Wybierz jedno zadanie, jednego czytelnika i jedno źródło prawdy. Potem opisz kroki prostym językiem, przetestuj je z kimś, kto ich nie pisał, i usuń wszystko, co nie pomaga czytelnikowi wykonać zadania.

Przed pisaniem

Dobra dokumentacja techniczna zaczyna się przed pierwszym zdaniem. Najpierw wybierz jedno zadanie. Na przykład napisz o „podłączeniu nowej bramki płatności”, a nie o „udokumentowaniu aplikacji”. To daje Ci jasną linię mety i sprawia, że strona pozostaje przydatna.

Potem określ czytelnika. Programista potrzebuje notatek o konfiguracji, komend i przypadków brzegowych. Konsultant wsparcia potrzebuje objawów, sprawdzeń i poprawek. Lider projektu może potrzebować statusu, zależności i notatek do przekazania. Jedna strona może dobrze służyć jednej z tych osób, albo zawieść wszystkie trzy.

Następnie zbierz źródło prawdy. Mogą to być kod, zgłoszenia, zrzuty ekranu, notatki projektowe, logi, runbook albo stara instrukcja, która wciąż ma jedną dobrą sekcję. Jeśli dwa źródła się nie zgadzają, zatrzymaj się i zapytaj, które jest ważniejsze, zanim zaczniesz pisać szkic.

Wybierz format, zanim zaczniesz pisać. Przewodnik konfiguracji, strona referencyjna i strona rozwiązywania problemów każda potrzebuje innej budowy. Dla sterownika biurka z regulacją wysokości przewodnik konfiguracji może wyjaśniać parowanie i kalibrację. Strona referencyjna może podawać nazwy przycisków i znaczenie kontrolek. Strona rozwiązywania problemów może opisywać zacięty mechanizm podnoszenia albo migającą kontrolkę błędu.

Jak pisać dokumentację techniczną

• Najpierw napisz efekt. Powiedz, co czytelnik będzie mógł zrobić, gdy strona zadziała. Przykład: „Na końcu będziesz mieć aplikację staging połączoną ze Stripe.”
• Użyj prostego układu: cel, czego potrzebujesz, kroki, efekt, poprawki. Dzięki temu czytelnik idzie dalej.
• Opisz jedną czynność w jednym kroku. „Otwórz konsolę administracyjną. Wybierz Billing. Wybierz Add payment method.” Tak jest łatwiej to śledzić niż długi akapit z pięcioma czasownikami.
• Używaj dokładnych nazw przycisków, pól, folderów, komend, kodów błędów i nazw plików. Jeśli na ekranie jest Add payment method, nie zmieniaj tego w dokumencie na New card.
• Utrzymuj stałe nazewnictwo. Jeśli w kroku 1 piszesz workspace, nie przechodź w kroku 4 na project area.
• Umieść prawdopodobny problem obok kroku, który go powoduje. Jeśli problemem często jest dostęp, napisz to właśnie tam. Przykład: „Jeśli nie ma przycisku, sprawdź, czy masz dostęp Billing Admin.”
• Używaj przykładów, które można skopiować, dla oprogramowania i kodu. Pokaż komendę, a zaraz po niej pokaż oczekiwany wynik. To pomaga czytelnikowi szybko sprawdzić własny ekran.
• Pisz krótkie akapity. Jeden akapit, jedna myśl, i to wystarczy. Jeśli akapit ma za dużo treści, podziel go na dwa.
• Usuń wszystko, co nie pomaga komuś zakończyć zadania. Tło jest przydatne tylko wtedy, gdy zapobiega błędowi.
• Dodaj następny krok na końcu. Na przykład podlinkuj stronę testową, stronę rozwiązywania problemów albo część konfiguracji, która jest dalej.

Prosty szablon kroku

Stały format kroku sprawia, że dokumentacja jest czytelna, gdy zadanie robi się złożone. Użyj takiej budowy dla każdego kroku: działanie, efekt, poprawka, jeśli potrzebna. To działa przy konfiguracji oprogramowania, przekazywaniu projektów i procesach opartych na komendach.

Przykład dla strony dla programisty: „Uruchom npm install. Powinieneś zobaczyć aktualizację listy pakietów. Jeśli się nie uda, sprawdź, czy zainstalowany jest Node 20.” To daje czytelnikowi coś do zrobienia, czegoś do oczekiwania i coś do sprawdzenia.

Przed: „Potem zajmij się problemem z zależnością.” Po: „Uruchom npm install. Jeśli zobaczysz błąd uprawnień, otwórz ponownie terminal jako użytkownik z dostępem do zapisu.” Druga wersja jest wolniejsza w pisaniu i szybsza w użyciu.

Dla strony sterownika biurka możesz napisać: „Przytrzymaj przyciski góra i dół przez trzy sekundy. Wyświetlacz powinien zamigać raz. Jeśli tak się nie stanie, odłącz sterownik i spróbuj ponownie.” To jest prosty, sprawdzalny i konkretny opis.

Co powinna zawierać dobra dokumentacja techniczna

Przydatna strona zwykle ma taką kolejność: tytuł, krótki wstęp, wymagania wstępne, kroki, oczekiwany efekt, poprawki, następny krok. Ta kolejność działa, bo odpowiada na pytania czytelnika w tej samej kolejności, w jakiej się pojawiają.

Tytuł powinien nazwać zadanie. Wstęp powinien powiedzieć czytelnikowi, dla kogo jest strona i czego dotyczy. Wymagania wstępne powinny wymieniać tylko to, co blokuje postęp, na przykład konto, kabel, wersję albo logowanie.

Kroki powinny być w prawdziwej kolejności, a nie w takiej, która brzmi sprytnie. Ostrzeżenia dodawaj tylko tam, gdzie mają znaczenie. Dodaj krótką sekcję poprawek dla najczęstszych pomyłek. Zakończ jasnym punktem końcowym, takim jak test albo przekazanie.

Dla strony konfiguracji bramki płatności może to wyglądać tak: „Połącz Stripe z aplikacją testową. Potrzebujesz dostępu administratora i klucza testowego. Wykonaj kroki, aby wkleić klucz, zapisać ustawienie i wykonać płatność testową. Jeśli test się nie uda, sprawdź klucz i uprawnienia konta. Potem przejdź do strony konfiguracji webhooka”

Przetestuj przed publikacją

Nie ufaj szkicowi tylko dlatego, że Tobie czyta się go dobrze. Daj go komuś, kto go nie pisał. Poproś, żeby przeszedł przez niego bez pomocy. Obserwuj, gdzie robi przerwę, zgaduje albo wraca do wcześniejszego miejsca.

Jeśli robi przerwę, strona może nie mieć wymagania wstępnego albo małego kroku konfiguracji. Dodaj ten krok blisko pierwszego miejsca, w którym jest potrzebny.

Jeśli zgaduje, sformułowanie jest niejasne. Zastąp „wpisz właściwą wartość” dokładną nazwą pola, etykietą albo ścieżką do pliku.

Jeśli wraca do wcześniejszego miejsca, kolejność jest zła. Przenieś krok wcześniej albo podziel stronę, żeby czytelnik nie musiał skakać po tekście.

Spróbuj naprawić mylący fragment, a nie tylko zdanie wokół niego. Czasem prawdziwą poprawką jest nowe wymaganie wstępne, podmiana zrzutu ekranu albo druga strona.

Na szybki test przejdź przez tools manual check. Jeśli potrzebujesz tego samego nawyku dla instrukcji fizycznych, porównaj strukturę z this guide.

Co zwykle idzie nie tak

Najczęstszy problem to za dużo kontekstu i za mało działania. Czytelnik nie potrzebuje lekcji historii przed nazwą przycisku.

Inny błąd to mieszanie zadań na jednej stronie. Konfiguracja, rozwiązywanie problemów i materiały referencyjne walczą o miejsce. Rozdziel je, gdy czytelnik musi przełączyć sposób myślenia.

Zrzuty ekranu szybko się starzeją. Używaj ich tylko do ekranów, które rzadko się zmieniają. Gdy etykiety często się przesuwają, lepiej użyj krótkiego dymku albo przyciętego obrazu zamiast pełnoekranowego zrzutu.

Niejasne słowa też sprawiają kłopoty. Pomijaj „po prostu”, „łatwo” i „tylko”. Nie naprawią zaciętego wdrożenia ani brakującego uprawnienia.

Gdy strona wydaje się zbyt rozbudowana, najpierw usuń dodatki. Zostaw kroki, które prowadzą czytelnika do działającego efektu.

Ile to trwa

Krótka strona z instrukcją może zająć 30 do 60 minutes, jeśli materiał źródłowy jest czysty, a zadanie proste.

Typowy poradnik konfiguracji oprogramowania zwykle zajmuje 2 to 4 hours, gdy doliczysz przygotowanie, sprawdzanie kroków i redakcję.

Większa strona projektu z wyjątkami, zrzutami ekranu i rundami akceptacji może zająć większość dnia.

Najwięcej czasu zwykle zajmuje sprawdzenie, czy kroki naprawdę działają, a nie samo ich spisanie. Jeśli proces jest chaotyczny, pisz dokumentację w trakcie wykonywania zadania. To szybko wyłapuje brakujące kliknięcia, ukryte założenia i niezręczne sformułowania.

Kiedy pomaga wersja wideo

Tekstowa strona nadal najlepiej sprawdza się do wyszukiwania, odwołań i dokładnego kopiowania treści. Wideo pomaga, gdy zadanie ma wiele kroków, zmieniające się ekrany albo powtarzające się pytania do supportu. To częste przy onboardingu, konfiguracji i praktycznych procedurach.

Jeśli masz już instrukcję montażu lub stronę z instrukcją, krótka wersja filmowa może być obok niej. Manual to Video zamienia istniejącą instrukcję montażu w animowany, podpisany film instruktażowy krok po kroku, w kolorach Twojej marki i z Twoim logo. Może też działać z QR na instrukcji montażu, pudełku, stronie produktu albo w artykule pomocy.