Obietnica i grupa
Dla kogo: ten tekst jest dla autora dokumentacji, który chce, żeby czytelnik bez bólu skopiował przykład i osiągnął efekt. Decyzja już teraz: jeśli zależy Ci na szybkim sukcesie użytkownika — zacznij od prostego, działającego przykładu i opisanych kroków.
Szybkie pytania i błyskawiczne odpowiedzi
Czy przykład ma być kompletny czy mikro? Krótki, kompletny przykład zwykle wygrywa — pokazuje efekt bez nadmiaru kontekstu.
Czy trzeba dodawać złe przykłady (anti-patterny)? Tak, ale tylko gdy pomagają uniknąć realnego błędu.
Czy komentarze w kodzie są potrzebne? Tak — krótki komentarz wyjaśniający punkt skupienia zwiększa użyteczność.
Czym jest "dobry przykład"
Dobry przykład to minimalny, poprawny fragment, który:
działa po skopiowaniu (bez dodatkowej konfiguracji),
ma jasny opis celu (1 zdanie),
pokazuje typowe przypadki użycia.
MDN zaleca dodawanie przykładów oraz krótkich opisów przed i po przykładzie — to pomaga zrozumieć, co robi kod i jakie są ograniczenia. ([developer.mozilla.org)
Jak zacząć — praktyczna ścieżka (5 minut)
Wybierz najbardziej typowy przypadek użycia i przygotuj działający kod, który użytkownik może skopiować.
Dodaj jednowierszowy opis: "Co robi ten przykład" i krótką listę wymagań (np. wersja języka, biblioteka).
Przetestuj przykład w czystym środowisku (sandbox, kontener, repl). Jeśli to kod frontendu, sprawdź w przeglądarce; jeśli backend — uruchom lokalnie.
Opublikuj i od razu sprawdź, że kopiuj-wklej działa.
Krótka procedura testu
Uruchom przykład w środowisku, które ma minimalną konfigurację wymaganą przez przykład. Jeżeli wymagane są zależności, podaj precyzyjne polecenie instalacji (np. pip install xyz lub npm install xyz). MDN podkreśla, że przykład powinien być możliwy do uruchomienia i że autor jest odpowiedzialny za jego poprawność. ([developer.mozilla.org)
Fakt → Skutek → Werdykt
Fakt: czytelnik zwykle kopiuje i testuje pierwszy przykład, który widzi.
Skutek w praktyce: jeśli ten przykład nie działa od razu — traci zaufanie i przerwie dalsze czytanie.
Werdykt: priorytet numer jeden to działający, minimalny przykład; dopiero potem rozbudowane scenariusze.
Porównanie typów przykładów
| Typ przykładu | Kiedy używać | Mini-werdykt |
|---|---|---|
| Krótki, kompletny (copy-paste) | Pierwszy przykład na stronie | Najważniejszy — zawsze |
| Pełny projekt (repozytorium) | Gdy chcesz pokazać end-to-end | Przydatny, ale nie jako pierwszy krok |
| Zły przykład / anti-pattern | Gdy ryzyko błędu jest powszechne | Używaj oszczędnie — tylko gdy realne |
Plusy i typowe skargi
Plusy:
Ułatwiają szybkie rozpoczęcie pracy.
Redukują wsparcie techniczne (mniej zgłoszeń "nie działa").
Typowe skargi:
"Przykład nie działa po skopiowaniu" — najczęstsza.
"Brakuje wersji narzędzi/dep." — zawsze podawaj wersje.
Synteza: jeśli chcesz zmniejszyć frustrację użytkownika, pokaż najpierw krótki działający przykład z listą minimalnych wymagań.
Kiedy przykład to nie wystarczy
Jeśli przykład zależy od zewnętrznej usługi lub konfiguracji środowiska, napisz to jawnie i podaj kroki weryfikacji (np. jak uzyskać klucz API, gdzie sprawdzić logi). Jeśli nie jesteś pewien kompatybilności — napisz, że to niepewne i podaj, gdzie czytelnik może to szybko zweryfikować (np. odnośnik do changelogu lub repozytorium projektu). Jeśli nie masz pewności co do wersji, przetestuj w najnowszym LTS i podaj wynik.
Gdzie uczyć się dobrych praktyk
Dobry punkt odniesienia to przewodnik stylu pisania MDN, który opisuje role przykładów i zasady ich konstruowania — warto się z nim zapoznać. [MDN: Writing style guide]. ([developer.mozilla.org)
Zakończenie — jednoznaczna puenta
Idealne dla: autorów dokumentacji i developerów, którzy chcą, żeby użytkownik osiągnął efekt szybko.
Będzie frustrować: jeśli publikujesz tylko fragmenty bez instrukcji uruchomienia — wtedy wybierz najpierw prosty, działający przykład.
Podstawowy next step (60–300 s): przygotuj jeden minimalny przykład, sprawdź go w czystym środowisku i dodaj wersje zależności. To zwraca wyraźny ROI w postaci mniejszej liczby zgłoszeń i wyższego zaufania użytkownika.
