Hopp til innhold

Napisz instrukcję obsługi

Relevante sider
Andre relevante sider
Skip to content

To jest tłumaczenie maszynowe i może zawierać błędy!

Krótko podsumowując
  • Instrukcja użytkownika pomaga konkretnej osobie w wykonaniu jednego konkretnego zadania.
  • Każda instrukcja ma jedno działanie i mówi, czego użytkownik powinien szukać na końcu.
  • Instrukcja nie jest kompletna, dopóki ktoś niezaznajomiony z systemem jej nie wykonał.

Kto powinien z niej korzystać?

Zawsze najpierw zadaj pytanie: Kto będzie korzystał z instrukcji i co powinno być osiągnięte po jej ukończeniu?

Nowy pracownik IT znający terminal potrzebuje innej instrukcji niż nauczyciel, który nigdy go nie otworzył. Dlatego ten sam system może wymagać kilku różnych instrukcji. Określ, co odbiorca już wie, ma dostęp do jakich zasobów oraz jakie terminy mu są nieznane.

Jaki to jest ten dokument?

Instrukcja obsługi użytkownika to instrukcja działania: pomaga użytkownikowi w wykonaniu jednego zadania. Nie jest podręcznikiem naukowym, encyklopedią ani wyjaśnieniem, dlaczego system działa tak, jak działa.

Typ dokumentu Pytanie czytelnika Przykład
Instrukcja działania Jak to zrobić? Tak publikujesz nową wersję aplikacji
Szkolenie Jak się tego nauczyć? Twój pierwszy kontener, krok po kroku
Materiał referencyjny Jaka jest wartość lub polecenie? Lista portów i usług
Wyjaśnienie Dlaczego to działa tak? Dlaczego używamy serwera odwrotnego (reverse proxy)

Jeśli użytkownik potrzebuje wyjaśnień podczas pracy, trzymaj je krótko i umieszczaj tam, gdzie ich potrzebuje.

Części instrukcji

Część Na co odpowiada
Cel Czego użytkownik osiągnął po zastosowaniu się do instrukcji?
Przed rozpoczęciem Jakie uprawnienia, programy, pliki i wiedza wstępna są wymagane?
Kroki krok po kroku Co robi użytkownik, w jakiej kolejności i na co powinien zwrócić uwagę po każdym kroku?
Przykłady Jak wygląda polecenie, ustawienie lub poprawny wynik?
Rozwiązywanie problemów Co robi użytkownik, gdy rezultat nie jest taki, jak oczekiwano?
W razie potrzeby cofnięcia zmian Jak przywraca się zmianę, która poszła źle?
Lista kontrolna Jak użytkownik sprawdza pod koniec, że wszystko jest prawidłowe?
Ważne wskazówki Czego nauczyłeś się, co użytkownik powinien wiedzieć?
Źródła i weryfikacja Na jakich źródłach, wersji i środowisku testowym opiera się instrukcja?

Jak napisać krok

Zasady opierają się na normach dotyczących instrukcji obsługi i dokumentacji użytkownika (IEC/IEEE 82079-1 oraz ISO/IEC/IEEE 26514).

  • Zaczynaj każdy czasownik w trybie rozkazującym: „Otwórz”, „Uruchom”, „Sprawdź”.
  • Wykonuj jedną czynność na krok i jedna instrukcja na zdanie. Zachowuj długość zdań poniżej około 20 słów.
  • Opisuj to, co użytkownik ma zobaczyć po zakończeniu kroku.
  • Umieszczaj ostrzeżenia przed krokiem, do którego odnoszą się, a nie po nim.
  • Używaj tych samych terminów konsekwentnie przez cały tekst. Jeśli gdzieś nazwana jest jako „terminal”, nie może być nazywana inaczej, np. „konsola”.
  • Wyjaśniaj termin fachowy przy pierwszym użyciu.

Słaby krok:

Skonfiguruj stronę internetową i upewnij się, że wszystko działa.
Lepszy krok:

3. Sprawdź konfigurację

Uruchom:

sudo nginx -t

Powinieneś zobaczyć:

nginx: configuration file /etc/nginx/nginx.conf test is successful

Jeśli widzisz coś innego, przejdź do „Rozwiązywanie problemów”.

Polecenie, oczekiwany wynik i placeholdery

  • Umieszczaj polecenia w bloku kodu, a oczekiwany wynik w osobnym bloku poniżej.
  • Używaj formatowania kodu dla nazw plików, ścieżek plików i poleceń w tekście ciągłym, na przykład /etc/nginx/.
  • Nigdy nie wpisuj prawdziwych haseł, kluczy ani adresów wewnętrznych. Używaj wyraźnych placeholderów: <server-ip>, <nazwa_użytkownika>, <domena>.
  • Zachowuj linie kodu do około 70 znaków, aby nie były ucinane przy wydruku na papierze.

Rozwiązywanie problemów

Skup się na rozwiązywaniu problemów wokół tego, co widzi użytkownik:

Objawienie → możliwe przyczyny → badanie → rozwiązanie → weryfikacja
Objaw Możliwa przyczyna Diagnostyka Rozwiązanie Jak sprawdzić, że problem został rozwiązany
Strona internetowa wyświetla „502 Bad Gateway” Usługa w tle nie odpowiada Uruchom docker compose ps i sprawdź, czy kontener działa Uruchom kontener za pomocą docker compose up -d Strona się ładuje, a docker compose ps pokazuje „Up” w kolumnie STATUS

Metoda opisana jest w [[Feilsokingsmetode Level 1 - Systematisk feilsøking|Metodzie rozwiązywania problemów]].

Zrzuty ekranu

Używaj zrzutu ekranu tylko wtedy, gdy pomaga użytkownikowi rozpoznać poprawny wynik. Przyciąć obraz, zaznaczyć najważniejsze elementy strzałką lub numerem i usunąć poufne informacje. Napisz alternatywny opis określający, co pokazuje obraz.

  • Windows: Klawisz Windows + Shift + S
  • Mac: Cmd + Shift + 4
![Menedżer proxy Nginxa pokazuje hosta proxy ze statusem Online](bilder/proxy-online.png)

Drukuj do PDF

  1. Otwórz przewodnik w podglądzie w programie VS Code lub otwórz plik na platformie GitHub.
  2. Wybierz drukowanie. System Windows: Ctrl + P. Mak: Cmd + P.
  3. Wybierz opcję „Zapisz jako PDF”.
  4. Przeglądaj dokument PDF. Sprawdź, czy żadne linie kodu, tabele ani obrazy nie są ucięte.

Zdobądź opinię przed dostarczeniem

Poproś kolegę lub koleżankę o przeczytanie instrukcji, zanim oznaczysz ją jako ukończoną. Osoba dająca informację zwrotną powinna odpowiadać zwięźle i wskazywać konkretne miejsce w tekście:

  1. Prawidłowość: Czy są kroki lub twierdzenia, co do których masz wątpliwości?
  2. Odbiorca i struktura: Czy jasno wynika, dla kogo przeznaczone jest opracowanie oraz co musi zostać zrobione na początku?
  3. Język i działanie: Czy każdy krok zawiera jedno działanie i oczekiwany rezultat? Czy terminy branżowe zostały wyjaśnione?
  4. Bezpieczeństwo: Czy znajduje się tam coś, czego nie powinno być opublikowane?

Wymień dwie mocne strony i dwie konkretne propozycje usprawnienia. Bądź uprzejmy i konkretny: „Sugeruję wyjaśnienie proxy w kroku 2, ponieważ …” przynosi więcej korzyści niż stwierdzenie „niejasny”. Więcej na temat udzielania informacji zwrotnej: NDLA Jak udzielać opinii?.

Zadanie 1 – Popraw słabe kroki

Przeformułuj każdy krok tak, aby zawierał jeden czasownik w trybie rozkazującym, jedno działanie oraz oczekiwany wynik. Rozbij kroki zawierające wiele działań na osobne elementy.

  1. „Teraz kontener musi zostać uruchomiony i należy sprawdzić, czy działa.”
  2. „Zmień konfigurację, a następnie przetestuj ją i załaduj ponownie.”
  3. „Zaloguj się na serwerze hasłem Sommer2026! i przejdź do folderu z witryną internetową.”

Zadanie 2 – Napisz krótki przewodnik

Wybierz zadanie, które możesz wykonać bez pomocy, na przykład uruchomienie kontenera lub opublikowanie zmiany na stronie internetowej.

  1. Napisz, dla kogo przeznaczony jest przewodnik oraz co mają umieć robić po jego przeczytaniu.
  2. Napisz od trzech do sześciu kroków z oczekiwanym wynikiem.
  3. Dodaj co najmniej jedną linię w sekcji rozwiązywania problemów.
  4. Poproś kolegę/koleżankę o podążanie za instrukcją w przewodniku, nie wyjaśniając niczego samemu/samej. Zareaguj tylko wtedy, gdy się zatrzyma/tamuje.

Więcej do przeczytania