Artykuł z rozwiązanego zgłoszenia powinien opisywać jeden objaw, potwierdzone środowisko, sprawdzoną naprawę i wynik weryfikacji. Usuń dane klienta i wyraźnie ogranicz instrukcję do przypadków, w których rzeczywiście działa.
Wybierz rozwiązany i odtwarzalny przypadek
Zacznij od zgłoszenia, dla którego potwierdzono przyczynę, wykonano naprawę i sprawdzono rezultat. Samo zamknięcie ticketu nie dowodzi, że rozwiązanie działa. Jeśli zgłoszenie zakończono bez potwierdzenia klienta lub testu, nie przedstawiaj go jako zweryfikowanej instrukcji.
Wybierz jeden objaw. Nie łącz kilku różnych problemów tylko dlatego, że trafiły do tego samego zespołu wsparcia. Artykuł ma pozwolić odbiorcy rozpoznać własny przypadek i sprawdzić, czy opisane środowisko jest zgodne.
Zanonimizuj materiał wejściowy
Usuń nazwiska, adresy, treść prywatnych dokumentów, numery kont, identyfikatory sesji i sekrety techniczne. Zrzuty ekranu sprawdź osobno, bo mogą pokazywać dane, których nie ma w tekście.
Zachowaj informacje techniczne potrzebne do rozpoznania przypadku: produkt, wersję, środowisko, objaw i warunek wystąpienia. Jeśli konfiguracja identyfikuje konkretnego klienta, przygotuj bezpieczny opis zachowujący istotę problemu. Nie publikuj całej korespondencji.
Użyj szablonu objaw–środowisko–naprawa
- Objaw: co odbiorca widzi i kiedy problem występuje.
- Środowisko: produkt, wersja, system oraz istotna konfiguracja.
- Warunek rozpoznania: jak sprawdzić, czy instrukcja pasuje.
- Naprawa: kroki potwierdzone dla tego przypadku.
- Weryfikacja: jaki wynik oznacza skuteczne rozwiązanie.
- Zakres i eskalacja: kiedy przerwać lub skontaktować się ze wsparciem.
Rozróżnij działanie naprawcze od testu diagnostycznego. Krok, który tylko zbiera informacje, nie powinien być przedstawiony jako rozwiązanie. Przy operacjach wymagających zabezpieczenia danych wskaż potwierdzoną procedurę produktu zamiast dopisywać własną.
Przykład struktury artykułu
Poniższy przypadek jest fikcyjny i nie opisuje usterki Semly. W przykładowej aplikacji dokumentowej 2.4.0 po potwierdzonej zmianie uprawnienia otwarta lista nie pokazywała nowego dokumentu. Ponowne załadowanie widoku przywracało aktualną listę; nie zmieniało uprawnień.
Objaw: brak nowego dokumentu w już otwartym widoku. Środowisko: wersja 2.4.0 i sesja rozpoczęta przed zmianą uprawnienia. Warunek rozpoznania: dokument jest dostępny w nowo otwartym widoku tego samego konta.
Naprawa w tym przykładzie: zapisać niezapisane działania, następnie ponownie załadować widok zgodnie z instrukcją aplikacji. Weryfikacja: dokument pojawia się na liście i daje się otworzyć z właściwym uprawnieniem. Jeśli nie pojawia się również w nowym widoku, ten przypadek nie został potwierdzony; potrzebna jest dalsza diagnostyka.
Opisz ograniczenia bez rozszerzania rozwiązania
Działanie potwierdzone w jednej wersji nie musi usuwać podobnego objawu w każdej innej. Wymień wersje i konfiguracje faktycznie sprawdzone. Nie dopisuj obsługi dodatkowych platform z powodu podobnego wyglądu interfejsu.
Nie obiecuj, że odświeżenie naprawi błędne uprawnienia albo brak danych w systemie. To inne przyczyny wymagające innych procedur. Jasny warunek rozpoznania chroni czytelnika przed powtarzaniem kroku, który nie odpowiada jego problemowi.
Zweryfikuj tekst jak użytkownik
Poproś osobę techniczną o odtworzenie przypadku w bezpiecznym środowisku i przejście kroków bez czytania ticketu. Sprawdź, czy instrukcja zawiera wszystkie warunki i czy wynik weryfikacji jest jednoznaczny.
Jeśli test wymaga dodatkowej informacji, uzupełnij środowisko lub warunek rozpoznania. Artykuł nie powinien polegać na wiedzy dostępnej tylko autorowi. Dopiero po potwierdzeniu treści oznacz go jako gotowy do dalszej redakcji.
Zapisz wersję i zachowaj znaczenie tłumaczeń
Przechowuj datę weryfikacji i osobę odpowiedzialną. Po zmianie produktu sprawdź nadal aktualne warunki oraz kroki. Nowe rozwiązanie dla innej przyczyny nie powinno być dopisane jako niezwiązany rozdział tego samego poradnika.
W tłumaczeniach zachowaj wersję, objaw, kolejność kroków i kryterium powodzenia. Tłumacz komunikaty z uwzględnieniem rzeczywistego interfejsu. Rezultatem jest jedna sprawdzalna instrukcja dla jednego rozpoznawalnego przypadku, a nie ogólny katalog tematów wsparcia.
