Przewodniki krok po kroku¶
Przewodniki krok po kroku to instrukcje, które prowadzą czytelnika przez problem lub w kierunku wyniku. Przewodniki krok po kroku są ukierunkowane na cel.
Przewodnik krok po kroku pomaga użytkownikowi coś zrobić, poprawnie i bezpiecznie; prowadzi użytkownika w jego działaniu.
Jest związany z pracą - nawigowaniem z jednej strony na drugą w rzeczywistym polu problemu.
Przykłady mogłyby być: jak skalibrować tablicę radaru; jak używać uchwytów w pytest; jak skonfigurować polityki opóźnienia ponownego połączenia. Z drugiej strony, jak zbudować aplikację webową nie jest - to nie jest adresowanie konkretnego celu lub problemu, to jest szeroko otwarta sfera umiejętności.
Przewodniki krok po kroku są ważne nie tylko dlatego, że użytkownicy muszą być w stanie coś osiągnąć: lista przewodników krok po kroku w twojej dokumentacji pomaga nakreślić obraz tego, co twój produkt może faktycznie zrobić. Bogata lista przewodników krok po kroku jest zachęcającą sugestią możliwości produktu.
Dobrze napisane przewodniki krok po kroku, które adresują właściwe pytania, prawdopodobnie będą najczęściej czytanymi sekcjami twojej dokumentacji.
Przewodniki krok po kroku adresowane do problemów¶
Przewodniki krok po kroku muszą być pisane z perspektywy użytkownika, a nie maszyny. Przewodnik krok po kroku reprezentuje coś, co ktoś musi zrobić. Jest zdefiniowany, innymi słowy, przez potrzeby użytkownika. Każdy przewodnik krok po kroku powinien odpowiadać na ludzki projekt, innymi słowy. Powinien pokazywać, co człowiek musi zrobić, przy użyciu dostępnych narzędzi, aby uzyskać potrzebny wynik.
Jest to w silnym kontraście do powszechnego wzorca dla przewodników krok po kroku, który często przeważa, w którym przewodniki krok po kroku są definiowane przez operacje, które można wykonać za pomocą narzędzia lub systemu. Problem z tym ostatnim wzorcem polega na tym, że oferuje on niewielką wartość użytkownikowi; nie jest adresowany do żadnej potrzeby, którą użytkownik ma. Zamiast tego jest skupiony na narzędziu, na przeprowadzaniu maszyny przez jej ruchy.
Jest to zasadniczo rozróżnienie znaczeniowości. Znaczenie jest nadawane przez cel i potrzebę. Nie ma celu ani potrzeby w funkcjonalności maszyny. Jest to po prostu seria przyczyn i skutków, wejść i wyjść.
Rozważ:
„Aby wyłączyć przepływ wody, obróć kran w prawo.”
„Aby wdrożyć pożądaną konfigurację bazy danych, wybierz odpowiednie opcje i naciśnij Wdróż.”
Przykłady powyżej wyglądają jak przykłady wskazówek, ale nimi nie są.
Reprezentują głównie bezużyteczne informacje, które każdy z podstawową kompetencją - każdy, kto pracuje w tej dziedzinie - powinien znać. Standardowe interfejsy i ogólnie oczekiwana wiedza powinny dość jasno wskazywać, jaki efekt będą miały większość działań.
Po drugie, są oderwane od celu. To, co użytkownik musi wiedzieć, może być takimi rzeczami, jak:
ile wody puścić i jak energicznie, dla określonego celu
które opcje konfiguracji bazy danych odpowiadają konkretnym potrzebom w świecie rzeczywistym
Narzędzia pojawiają się w przewodnikach krok po kroku jako przypadkowi statyści, środki do celu użytkownika. Oczywiście, czasami określony cel jest ściśle związany z określonym narzędziem lub częścią systemu, i wtedy przewodnik krok po kroku rzeczywiście koncentruje się na tym. Równie często przewodnik krok po kroku będzie przekraczał różne narzędzia lub części systemu, łącząc je razem w serii działań zdefiniowanych przez coś, co człowiek musi zrobić. W obu przypadkach to ten projekt definiuje, co przewodnik krok po kroku musi obejmować.
Czego przewodniki krok po kroku nie są¶
Przewodniki krok po kroku są całkowicie odrębne od tutoriali. Często są mylone, ale potrzeby użytkownika, które zaspokajają, są dość różne. Mylenie ich jest u podstaw wielu trudności, które nękają dokumentację. Zobacz Różnica między samouczkiem a poradnikiem krok po kroku w celu omówienia tego rozróżnienia.
W innym nieporozumieniu, przewodniki krok po kroku są często postrzegane jedynie jako przewodniki proceduralne. Ale rozwiązywanie problemu lub osiągnięcie zadania nie zawsze może być sprowadzone do procedury. Rzeczywiste problemy nie zawsze oferują się do liniowych rozwiązań. Sekwencje działań w przewodniku krok po kroku czasami muszą się rozgałęziać i nakładać, i mają wiele punktów wejścia i wyjścia. Często przewodnik krok po kroku będzie wymagał od użytkownika polegania na jego osądzie w stosowaniu wskazówek, które może zapewnić.
Kluczowe zasady¶
Przewodnik krok po kroku jest związany z pracą - zadaniem lub problemem, z praktycznym celem. Utrzymuj skupienie na tym celu.
Wszystko, co jest dodane, rozprasza zarówno ciebie, jak i użytkownika oraz rozmywa użyteczną moc przewodnika. Typowe pokusy to wyjaśnianie lub dostarczanie referencji dla kompletności. Żadne z tych nie jest częścią prowadzenia użytkownika w jego pracy. Przeszkadzają w działaniu; jeśli są ważne, linkuj do nich.
Przewodnik krok po kroku służy pracy już kompetentnego użytkownika, któremu możesz założyć, że wie, co chce zrobić, i że będzie w stanie poprawnie wykonać twoje instrukcje.
Adresuj rzeczywistą złożoność¶
Przewodnik krok po kroku musi być adaptowalny do rzeczywistych przypadków użycia. Taki, który jest bezużyteczny dla każdego celu poza dokładnie wąskim, który omówiłeś, rzadko jest wartościowy. Nie możesz omówić każdego możliwego przypadku, więc musisz znaleźć sposoby, aby pozostać otwartym na zakres możliwości, w taki sposób, że użytkownik może dostosować twoje wskazówki do swoich potrzeb.
Pomijaj to, co niepotrzebne¶
W przewodnikach krok po kroku praktyczna użyteczność jest bardziej pomocna niż kompletność. Podczas gdy tutorial musi być kompletnym, end-to-end przewodnikiem, przewodnik krok po kroku nie musi. Powinien zaczynać się i kończyć w jakimś rozsądnym, znaczącym miejscu i wymagać od czytelnika połączenia go z własną pracą.
Podaj zestaw instrukcji¶
Przewodnik krok po kroku opisuje wykonalne rozwiązanie do rzeczywistego problemu lub zadania. Jest w formie kontraktu: jeśli stoisz przed tą sytuacją, wtedy możesz przejść przez nią, wykonując kroki przedstawione w tym podejściu. Kroki są w formie działań.
„Działania” w tym kontekście obejmują czynności fizyczne, ale także myślenie i osąd - rozwiązywanie problemu wymaga przemyślenia go. Przewodnik krok po kroku powinien odnosić się do tego, jak użytkownik myśli, a nie tylko co użytkownik robi.
Opisz logiczną sekwencję¶
Podstawowa struktura przewodnika krok po kroku to sekwencja. Implikuje logiczne uporządkowanie w czasie, że jest sens i znaczenie w tej konkretnej kolejności.
W wielu przypadkach kolejność jest po prostu narzucona przez to, jak rzeczy muszą być (na przykład krok drugi wymaga ukończenia kroku pierwszego). W tym przypadku jest oczywiste, w jakiej kolejności powinny iść twoje wskazówki.
Czasami potrzeba jest bardziej subtelna - może być możliwe wykonanie dwóch operacji w dowolnej kolejności, ale jeśli na przykład jedna operacja pomaga przygotować środowisko pracy użytkownika lub nawet jego myślenie w sposób, który przynosi korzyści drugiej, to dobry powód, aby umieścić ją jako pierwszą.
Szukaj przepływu¶
Cały czas staraj się osadzić swoje sekwencje we wzorcach aktywności i myślenia użytkownika, w taki sposób, że przewodnik nabiera przepływu: płynnego postępu.
Osiągnięcie przepływu oznacza skuteczne zrozumienie użytkownika. Zwracanie uwagi na sens i znaczenie w kolejności wymaga zwrócenia uwagi na sposób, w jaki ludzie myślą i działają, oraz na potrzeby osoby podążającej za wskazówkami.
Ponownie, może to być dość oczywiste: przepływ pracy, który wymaga od użytkownika wielokrotnego przełączania się między kontekstami i narzędziami, jest niezgrabny i nieefektywny. Ale powinieneś spojrzeć głębiej niż to. O czym prosisz użytkownika, aby myślał, i jak jego myślenie będzie przepływać od tematu do tematu podczas pracy? Jak długo wymagasz, aby użytkownik trzymał otwarte myśli, zanim będą mogły zostać rozwiązane w działaniu? Jeśli wymagasz od użytkownika powrotu do wcześniejszych kwestii, czy jest to konieczne czy możliwe do uniknięcia?
Przewodnik krok po kroku dotyczy nie tylko logicznego uporządkowania w czasie, ale działania mającego miejsce w czasie. Działanie, i przewodnik do niego, ma tempo i rytm. Źle osądzone tempo lub zakłócony rytm są szkodliwe dla przepływu.
W najlepszym wydaniu, dokumentacja krok po kroku daje użytkownikowi przepływ. Jest wyraźne doświadczenie napotkania przewodnika, który wydaje się przewidywać użytkownika - odpowiednik dokumentacji pomocnika, który ma narzędzie, po które miałeś sięgnąć, gotowe, aby podać ci je do ręki.
Zwracaj uwagę na nazewnictwo¶
Wybieraj tytuły, które dokładnie mówią, czego przewodnik krok po kroku uczy.
dobre: Jak zintegrować monitorowanie wydajności aplikacji
złe: Integracja monitorowania wydajności aplikacji (może dokument dotyczy tego, czy powinieneś to zrobić, a nie jak to zrobić)
bardzo złe: Monitorowanie wydajności aplikacji (może dotyczy jak - ale może dotyczy czy, a nawet tylko wyjaśnienia czym to jest)
Zauważ, że wyszukiwarki doceniają dobre tytuły tak samo jak ludzie.
Język przewodników krok po kroku¶
- Ten przewodnik pokazuje ci, jak…
Opisz jasno problem lub zadanie, które przewodnik pokazuje użytkownikowi, jak rozwiązać.
- Jeśli chcesz x, zrób y. Aby osiągnąć w, zrób z.
Używaj rozkazów warunkowych.
- Zobacz przewodnik referencyjny x, aby uzyskać pełną listę opcji.
Nie zanieczyszczaj swojego praktycznego przewodnika krok po kroku każdą możliwą rzeczą, którą użytkownik może zrobić związaną z x.
Zastosowane do jedzenia i gotowania¶
Rozważ przepis, doskonały model dla przewodnika krok po kroku. Przepis jasno definiuje, co zostanie osiągnięte, postępując zgodnie z nim, i odnosi się do konkretnego pytania (Jak zrobić…? lub Co mogę zrobić z…?).
Nie jest odpowiedzialnością przepisu nauczać cię, jak coś zrobić. Profesjonalny szef kuchni, który zrobił dokładnie tę samą rzecz wielokrotnie wcześniej, może nadal podążać za przepisem - nawet jeśli stworzył przepis - aby upewnić się, że zrobi to poprawnie.
Nawet podążanie za przepisem wymaga przynajmniej podstawowej kompetencji. Ktoś, kto nigdy wcześniej nie gotował, nie powinien być oczekiwany, aby z powodzeniem podążać za przepisem, więc przepis nie jest substytutem lekcji gotowania.
Ktoś, kto oczekiwał, że zostanie mu dostarczony przepis, i zamiast tego otrzymał lekcję gotowania, będzie rozczarowany i poirytowany. Podobnie, chociaż interesujące jest czytanie o kontekście lub historii konkretnego dania, jedyny czas, kiedy nie chcesz być konfrontowany z tym, to kiedy jesteś w trakcie próby jego zrobienia. Dobry przepis przestrzega dobrze ustalonego formatu, który wyklucza zarówno nauczanie, jak i dyskusję, i skupia się tylko na jak zrobić danie.