Różnica między samouczkiem a poradnikiem krok po kroku¶
W Diátaxis samouczki i poradniki krok po kroku są silnie rozróżniane. To rozróżnienie, które często nie jest dokonywane; w rzeczywistości najczęstszym pomieszaniem w dokumentacji produktów oprogramowania jest to między samouczkiem a poradnikiem krok po kroku.
Więc: czym jest różnica między samouczkami a poradnikami krok po kroku? Dlaczego to ma znaczenie? I dlaczego są mylone?
To są wszystkie dobre pytania. Zacznijmy od ostatniego. Jeśli to rozróżnienie jest naprawdę tak ważne, dlaczego nie jest bardziej oczywiste?
To, co mają wspólnego¶
W ważnych aspektach samouczki i poradniki krok po kroku są rzeczywiście podobne. Oba są praktycznymi przewodnikami: zawierają instrukcje dla użytkownika do wykonania. Nie służą do wyjaśniania czy przekazywania informacji. Istnieją po to, aby kierować użytkownikiem w tym, co ma zrobić, a nie co ma wiedzieć lub rozumieć.
Oba przedstawiają kroki dla czytelnika do wykonania i oba obiecują, że jeśli czytelnik wykona te kroki, dotrze do udanego zakończenia. Żaden z nich nie ma sensu, jeśli nie wykonuje się działań na rzeczywistym sprzęcie. Oba opisują uporządkowane sekwencje działań. Nie można oczekiwać sukcesu, jeśli nie wykonuje się działań we właściwej kolejności.
Są blisko spokrewnione, a jak wielu bliskich krewnych, mogą być mylone z sobą na pierwszy rzut oka.
To, co jest ważne, to potrzeby użytkownika¶
Diátaxis nalega, aby to, co jest ważne w dokumentacji, to potrzeby użytkownika, i to przez zwracanie uwagi na to, możemy prawidłowo odróżnić samouczki od poradników krok po kroku.
Czasem użytkownik jest w trakcie nauki, a czasem użytkownik jest w trakcie pracy. Dokumentacja musi służyć obu tym potrzebom.
Samouczek służy potrzebom użytkownika, który jest w trakcie nauki. Jego obowiązkiem jest zapewnienie udanego doświadczenia nauki. Poradnik krok po kroku służy potrzebom użytkownika, który jest w trakcie pracy. Jego obowiązkiem jest pomoc użytkownikowi w wykonaniu zadania. Są to całkowicie różne potrzeby i obowiązki, i to dlatego rozróżnienie między samouczkami a poradnikami krok po kroku jest ważne: samouczki są ukierunkowane na naukę, a poradniki krok po kroku są ukierunkowane na zadanie.
W trakcie nauki i w trakcie pracy¶
Możemy to rozważyć z perspektywy rzeczywistego przykładu. Załóżmy, że jesteś w medycynie: lekarzem, kimś, kto musi nabywać i stosować praktyczne, kliniczne umiejętności swojego fachu.
Jako lekarz, czasem będziesz w sytuacjach pracy, stosując swoje umiejętności, a czasem w sytuacjach nauki, nabywając umiejętności (wszyscy dobrzy lekarze, nawet ci z długimi karierami za sobą, wciąż się uczą, aby doskonalić swoje umiejętności).
W trakcie nauki¶
Na wczesnym etapie szkolenia nauczysz się, jak zszywać ranę. Zaczniesz w laboratorium z kolegami, przy stołach z małymi podkładkami skórnymi przed sobą (podkładki skórne to bloki syntetycznego materiału w różnych warstwach, które reprezentują naskórek, tłuszcz i inne tkanki. Mają podobną twardość i fakturę do ludzkiego ciała i zachowują się nieco podobnie, gdy są cięte i zszywane). Otrzymasz dokładnie to, czego potrzebujesz - rękawiczki, skalpel, igłę, nić itp. - i krok po kroku zostanie ci pokazane, co robić i co się stanie, gdy to zrobisz.
A potem przychodzi twoja kolej. Podniesiesz skalpel i niepewnie przejedziesz nim po wierzchu podkładki, wykonując nieskuteczne nacięcie w górnej warstwie (może asystent nauczyciela będzie się z ciebie naśmiewał, pytając, co to biedne podkładki zrobiły, że zasługują na taką brzydką rysę). Twój sąsiad będzie przerażony swoją własną próbą, niechlujnym cięciem o dzikich głębokościach, które wygląda jak coś z walki na noże.
Po kilku próbach, z informacją zwrotną i korektą od tutora, wykonasz w miarę czyste cięcie, które w większości przejdzie przez warstwę tłuszczu, nie przecinając mięśnia poniżej. Sukces!
Ale teraz prosisz cię o zszycie tego z powrotem! Będziesz obserwować, jak tutor demonstruje to zręcznie i precyzyjnie, zamykając ranę w podkładce kilkoma gładkimi, równymi szwami. Ty, z drugiej strony, będziesz niezdarnie obchodzić się z nicią. Będziesz trzymać rzeczy w złej ręce i w zły sposób i kłaść je w złych miejscach. Upuścisz igłę. Nić wypadnie. Zostaniesz skarcony za nieutrzymywanie sterylności.
W końcu rzeczywiście zabierzesz się za zszywanie rany. Nakłujesz skórę w złych miejscach i rozerwiesz brzegi cięcia. Twój końcowy wynik będzie nieestetyczną sceną rozciągniętej i pomarszczonej skóry oraz niezgrabnych, niechlujnych szwów. Asystenci nauczycieli będą mieli krytyczne uwagi nawet co do tych części, które uważałeś za wykonane poprawnie.
Ale, zszyjesz swoją pierwszą ranę. I wrócisz do tej lekcji raz po raz, i krok po kroku twoja niezdarność przekształci się w pewną praktykę. Nabędziesz podstawową biegłość. Nauczysz się przez działanie.
To jest samouczek. To jest lekcja, bezpiecznie w rękach instruktora, nauczyciela, który dba o interesy ucznia.
W trakcie pracy¶
Teraz pomyślmy o lekarzu w trakcie pracy. Jako lekarz w trakcie pracy, jesteś już kompetentny. Nauczyłeś się i doskonaliłeś kliniczne umiejętności, takie jak szycie ran, a także wiele innych, i potrafisz je łączyć na co dzień, aby zastosować je do sytuacji medycznych w prawdziwym świecie.
Rozważmy standardową appendektomię. Podręcznik kliniczny wymieni wymagany sprzęt i personel w sali operacyjnej. Pokaże, jak rozmieścić członków zespołu oraz jak ułożyć wymagane narzędzia, stojaki i monitory. Następnie krok po kroku przejdzie przez działania, które zespół będzie musiał wykonać, kończąc na formalnym przekazaniu pacjenta zespołowi pooperacyjnemu.
Podręcznik pokaże, jakie nacięcia należy wykonać i gdzie, ale będą one zależeć od tego, czy wykonujesz zabieg otwarty, czy laparoskopowy, czy masz przedoperacyjne obrazowanie, na którym możesz polegać, i tak dalej. Będzie zawierał specjalne kroki lub kontrole do wykonania w przypadku pacjenta będącego niemowlęciem lub nastolatkiem, lub gdy trzeba przejść na otwartą appendektomię w trakcie zabiegu. Wiele z tych kroków będzie miało formę jeśli to, to tamto.
Posiadanie podręcznika pomaga zapewnić, że wszystkie kroki zostaną wykonane we właściwej kolejności i żaden nie zostanie pominięty. Jako zespół, przejdziecie przez szczegóły procedury, aby przypomnieć sobie kluczowe kroki; czasem będziecie się do niego odwoływać w trakcie zabiegu.
Nawet w przypadku rutynowych operacji chirurgicznych, podręczniki kliniczne zawierają listy kroków i kontroli. Te podręczniki to poradniki krok po kroku. Nie są tam po to, aby cię uczyć - już masz swoje umiejętności. Już znasz te procesy. Są tam, aby bezpiecznie kierować cię w twojej praktyce klinicznej w celu wykonania konkretnego zadania - służą twojej pracy.
Zrozumienie rozróżnienia¶
Rozróżnienie między lekcją w szkole medycznej a podręcznikiem klinicznym to rozróżnienie między samouczkiem a poradnikiem krok po kroku.
Celem samouczka jest pomóc uczniowi nabyć podstawową biegłość.
Celem poradnika krok po kroku jest pomóc już kompetentnemu użytkownikowi wykonać konkretne zadanie prawidłowo.
Samouczek zapewnia doświadczenie nauki. Ludzie nabywają umiejętności poprzez praktyczne, hands-on doświadczenie. W samouczku ważne jest to, co robi uczący się, i co doświadcza podczas tego.
Poradnik krok po kroku kieruje pracą użytkownika.
Samouczek podąża starannie zarządzaną ścieżką, zaczynając od określonego punktu i zmierzając do zakończenia. Wzdłuż tej ścieżki uczący się musi mieć spotkania, które wymaga lekcja.
Poradnik krok po kroku dąży do udanego wyniku i kieruje użytkownika najbezpieczniejszą, najpewniejszą drogą do celu, ale ścieżka nie może być zarządzana: to prawdziwy świat, i wszystko może się pojawić, aby zakłócić podróż.
Samouczek zaznajamia uczącego się z pracą: z narzędziami, językiem, procesami i sposobem, w jaki to, nad czym pracują, zachowuje się i reaguje, i tak dalej. Jego zadaniem jest wprowadzenie ich, tworząc sztuczne, powtarzalne spotkanie z nimi.
Poradnik krok po kroku może i powinien zakładać znajomość ich wszystkich.
Samouczek odbywa się w zaaranżowanym otoczeniu, środowisku nauki, gdzie w miarę możliwości wszystko jest przygotowane z góry, aby zapewnić udane doświadczenie.
Poradnik krok po kroku stosuje się do prawdziwego świata, gdzie musisz radzić sobie z tym, co ci rzuci.
Samouczek eliminuje nieoczekiwane.
Poradnik krok po kroku musi przygotować się na nieoczekiwane, ostrzegając użytkownika o jego możliwości i zapewniając wskazówki, jak sobie z tym poradzić.
Ścieżka samouczka podąża jedną linią. Nie oferuje wyborów ani alternatyw.
Poradnik krok po kroku zwykle rozgałęzia się i rozwidla, opisując różne trasy do tego samego celu: Jeśli to, to tamto. W przypadku …, alternatywne podejście to….
Samouczek musi być bezpieczny. Uczącemu się nie powinna stać się żadna krzywda; zawsze musi być możliwość powrotu do początku i rozpoczęcia od nowa.
Poradnik krok po kroku nie może obiecać bezpieczeństwa; często jest tylko jedna szansa, aby zrobić to dobrze.
W samouczku odpowiedzialność spoczywa na nauczycielu. Jeśli uczący się wpakuje się w kłopoty, to problem nauczyciela, aby to naprawić.
W poradniku krok po kroku użytkownik ma odpowiedzialność za wpakowanie się w kłopoty i wydostanie się z nich.
Uczący się może nawet nie mieć wystarczającej kompetencji, aby zadać pytania, na które samouczek odpowiada.
Poradnik krok po kroku może zakładać, że użytkownik od razu zadaje właściwe pytania.
Samouczek jest wyraźny w kwestii podstawowych rzeczy - gdzie coś zrobić, gdzie to położyć, jak manipulować przedmiotami. Odnosi się do doświadczenia cielesnego - w naszym przykładzie medycznym, jak mocno nacisnąć, jak trzymać narzędzie; w samouczku do oprogramowania, mogłoby to być, gdzie wpisać polecenie lub jak długo czekać na odpowiedź.
Poradnik krok po kroku polega na tym jako wiedzy domyślnej - nawet wiedzy cielesnej.
Samouczek ma konkretne i szczegółowe podejście. Odnosi się do specyficznych, znanych, zdefiniowanych narzędzi, materiałów, procesów i warunków, które starannie przygotowaliśmy dla uczącego się.
Poradnik krok po kroku musi przyjąć ogólne podejście: wiele z tych rzeczy będzie nieznanych z góry lub różnych w każdym rzeczywistym przypadku.
Samouczek uczy ogólnych umiejętności i zasad, które później mogą być zastosowane w wielu przypadkach.
Użytkownik postępujący zgodnie z poradnikiem krok po kroku robi to w celu ukończenia konkretnego zadania.
Żadne z tych rozróżnień nie są arbitralne. Wszystkie wynikają z rozróżnienia między nauką a pracą, które rozumiemy jako kluczowe rozróżnienie w zrozumieniu, czego potrzebuje użytkownik dokumentacji.
Podstawy a zaawansowanie¶
Częstym, ale zrozumiałym pomieszaniem jest postrzeganie różnicy między samouczkami a poradnikami krok po kroku jako różnicy między podstawami a zaawansowaniem.
W końcu samouczki są dla uczących się, podczas gdy poradniki krok po kroku są dla już wykwalifikowanych praktyków. Samouczki muszą obejmować podstawy, podczas gdy poradniki krok po kroku muszą radzić sobie ze złożonościami, z którymi uczący się nie powinni się jeszcze mierzyć.
Jednak to nie cała historia. Rozważmy podręcznik procedur klinicznych: może to być podręcznik dla podstawowej rutynowej procedury, o bardzo niskiej złożoności. Może opisywać kroki dla przyziemnych spraw, takich jak prawidłowe wypełnienie dokumentacji lub utylizacja określonych materiałów. Poradniki krok po kroku mogą, i często powinny, obejmować podstawowe procedury.
Jednocześnie, nawet jako wykwalifikowany lekarz, znajdziesz się ponownie w sytuacjach nauki. Niektóre z nich mogą być bardzo zaawansowane i wyspecjalizowane, wymagające wysokiego poziomu umiejętności i ekspertyzy już na wstępie.
Załóżmy, że jesteś anestezjologiem z wieloletnim doświadczeniem, który uczestniczy w kursie: „Trudne intubacje noworodków”. Część praktyczna kursu będzie doświadczeniem edukacyjnym: lekcją, bezpiecznie pod okiem instruktorów, podczas której będziesz wykonywać określone ćwiczenia, aby rozwijać swoje umiejętności - tak samo, jak wiele lat temu, gdy uczyłeś się zszywać pierwszą ranę.
Złożoność jest jednak zupełnie inna, podobnie jak podstawowy poziom umiejętności wymagany nawet do uczestnictwa w doświadczeniu edukacyjnym. Ale forma jest taka sama, i służy temu samemu rodzajowi potrzeb, co ta znacznie wcześniejsza lekcja.
To samo dotyczy dokumentacji oprogramowania: tutorial może przedstawiać coś złożonego lub zaawansowanego. A przewodnik „jak to zrobić” może obejmować coś, co jest podstawowe lub dobrze znane. Różnica między nimi polega na potrzebach, które zaspokajają: naukę użytkownika, lub jego pracę.
Bezpieczeństwo i sukces¶
Zrozumienie tych różnic i powodów ich utrzymywania jest kluczowe dla tworzenia skutecznej dokumentacji. Podręcznik kliniczny, który zrównywałby edukację z praktyką, który próbowałby uczyć, jednocześnie zapewniając przewodnik do rzeczywistej procedury światowej, byłby dosłownie śmiertelnym dokumentem. Zabijałby ludzi.
W dyscyplinach takich jak dokumentacja oprogramowania, uchodzi nam na sucho wiele, ponieważ nasze pomyłki i błędy rzadko zabijają kogokolwiek. Jednak możemy powodować wiele drobnych niedogodności i niezadowolenia użytkowników, i dodajemy do tego za każdym razem, gdy publikujemy tutorial lub przewodnik „jak to zrobić”, który nie rozumie, czy jego celem jest pomoc użytkownikowi w nauce - nabywaniu umiejętności - czy w pracy - stosowaniu umiejętności.
Co więcej, krzywdzimy również siebie. Użytkownicy nie muszą używać naszego produktu. Jeśli nasza dokumentacja nie doprowadzi ich do sukcesu - jeśli nie spełni potrzeb, które mają na danym etapie cyklu interakcji z naszym produktem - znajdą coś innego, co to zrobi, jeśli będą mogli.
Zrównywanie tutoriali i przewodników „jak to zrobić” nie jest jedynym dokonywanym między różnymi rodzajami dokumentacji, ale jest jednym z najłatwiejszych do popełnienia. Jest również szczególnie szkodliwe, ponieważ ryzykuje utrudnianie nowicjuszom, których mamy nadzieję przekształcić w zaangażowanych użytkowników. Dla dobra tych użytkowników i naszego własnego produktu, właściwe rozróżnienie jest kluczem do sukcesu.