Wyjaśnienie¶

Wyjaśnienie to dyskursywne omówienie tematu, które umożliwia refleksję. Wyjaśnienie jest ukierunkowane na zrozumienie.

Wyjaśnienie pogłębia i poszerza zrozumienie czytelnika na temat przedmiotu. Przynosi jasność, światło i kontekst.

Pojęcie refleksji jest ważne. Refleksja występuje po czymś innym i zależy od czegoś innego, ale jednocześnie przynosi coś nowego - rzuca nowe światło - na temat.

Perspektywa wyjaśnienia jest wyższa i szersza niż pozostałych trzech rodzajów. Nie przyjmuje punktu widzenia użytkownika, jak w przewodniku krok po kroku, ani bliskiego widoku mechanizmu, jak materiał referencyjny. W każdym przypadku jej zakres to temat - „obszar wiedzy”, który w jakiś sposób musi być ograniczony w rozsądny, znaczący sposób.

Dla użytkownika wyjaśnienie łączy rzeczy. To odpowiedź na pytanie: Czy możesz mi opowiedzieć o …?

To dokumentacja, którą ma sens czytać z dala od samego produktu (można powiedzieć, że wyjaśnienie jest jedynym rodzajem dokumentacji, który może mieć sens czytać w wannie).

Wartość i miejsce wyjaśnienia¶

Wyjaśnienie i zrozumienie¶

Wyjaśnienie charakteryzuje się swoim dystansem od aktywnych trosk praktyka. Nie ma bezpośrednich implikacji dla tego, co oni robią, lub dla ich pracy. Oznacza to, że czasem jest postrzegane jako mniej ważne. To błąd; może być mniej pilne niż pozostałe trzy, ale nie jest mniej ważne. To nie jest luksus. Żaden praktyk rzemiosła nie może sobie pozwolić na brak zrozumienia tego rzemiosła i potrzebuje materiałów wyjaśniających, które pomogą to złożyć.

Słowo wyjaśnienie - i jego odpowiedniki w innych językach - odnoszą się do rozwijania, ujawniania tego, co ukryte w fałdach. Więc wyjaśnienie przynosi na światło dzienne rzeczy, które były implikowane lub zasłonięte.

Podobnie, słowa oznaczające zrozumienie dzielą rdzenie ze słowami oznaczającymi trzymanie lub chwytanie (jak w comprehend). To ważna część zrozumienia - umiejętność trzymania czegoś lub bycia w posiadaniu tego. Zrozumienie scala razem inne składniki naszego mistrzostwa w rzemiośle i sprawia, że staje się ono bezpiecznie nasze własne.

Zrozumienie nie pochodzi z wyjaśnienia, ale wyjaśnienie jest wymagane, aby utworzyć tę sieć, która pomaga trzymać wszystko razem. Bez niego wiedza praktyka o jego rzemiośle jest luźna i fragmentaryczna i krucha, a jego korzystanie z niej jest niepokojące.

Wyjaśnienie i jego granice¶

Dość często wyjaśnienie nie jest wyraźnie rozpoznawane w dokumentacji; a pomysł, że rzeczy muszą być wyjaśnione, jest często tylko słabo wyrażony. Zamiast tego, wyjaśnienie ma tendencję do bycia rozproszonym w małych porcjach w innych sekcjach.

Nie zawsze łatwo jest pisać dobre materiały wyjaśniające. Od czego zacząć? Nie jest też jasne, gdzie zakończyć. Jest w tym coś otwartego, co może dawać piszącemu zbyt wiele możliwości.

Tutoriale, przewodniki krok po kroku i referencje są wszystkie wyraźnie zdefiniowane w swoim zakresie przez coś, co również jest dobrze zdefiniowane: przez to, czego użytkownik musi się nauczyć, jakie zadanie użytkownik musi osiągnąć, lub po prostu przez zakres samej maszyny.

W przypadku wyjaśnienia, przydatne jest mieć prawdziwe lub wyobrażone dlaczego pytanie, które służy jako bodziec. W przeciwnym razie po prostu musisz narysować jakieś linie, które wyznaczają rozsądny obszar i być zadowolonym z tego.

Pisanie dobrego wyjaśnienia¶

Twórz połączenia¶

Pisząc wyjaśnienie, pomagasz tkać sieć zrozumienia dla swoich czytelników. Twórz połączenia z innymi rzeczami, nawet z rzeczami spoza bezpośredniego tematu, jeśli to pomaga.

Dostarcz kontekst¶

Dostarcz tło i kontekst w swoim wyjaśnieniu: wyjaśniaj dlaczego rzeczy są takie - decyzje projektowe, powody historyczne, ograniczenia techniczne - wyciągaj implikacje, wspominaj konkretne przykłady.

Mów o temacie¶

Przewodniki wyjaśniające są o temacie w tym sensie, że są wokół niego. Nawet nazwy twoich przewodników wyjaśniających powinny to odzwierciedlać; powinieneś być w stanie umieścić implikowane (lub nawet jawne) o przed każdym tytułem. Na przykład: O autoryzacji użytkownika, lub O politykach połączeń z bazą danych.

Przyznaj się do opinii i perspektywy¶

Opinia może wydawać się dziwną rzeczą do wprowadzenia do dokumentacji. Faktem jest, że cała ludzka aktywność i wiedza jest osadzona w opinii, z wierzeniami i myślami. Rzeczywistość każdego ludzkiego dzieła jest bogata w opinię, i to musi być częścią każdego zrozumienia tego.

Podobnie, każde zrozumienie pochodzi z perspektywy, z określonego punktu widzenia - co oznacza, że istnieją inne perspektywy i punkty widzenia. Wyjaśnienie może i musi rozważać alternatywy, kontrprzykłady lub wiele różnych podejść do tego samego pytania.

W wyjaśnieniu nie dajesz instrukcji ani nie opisujesz faktów - otwierasz temat do rozważenia. Pomaga myśleć o wyjaśnieniu jako o dyskusji: dyskusje mogą nawet rozważać i ważyć przeciwne opinie.

Utrzymuj wyjaśnienie ściśle ograniczone¶

Jednym z ryzyk wyjaśnienia jest to, że ma ono tendencję do wchłaniania innych rzeczy. Piszący, skupiony na omówieniu tematu, odczuwa potrzebę włączenia instrukcji lub opisu technicznego z nim związanego. Ale dokumentacja już ma inne miejsca dla tych, i pozwalanie im się wślizgnąć zakłóca samo wyjaśnienie, i usuwa je z widoku w odpowiednim miejscu.

Język wyjaśnienia¶

Powód, dla którego x jest taki, to historycznie y …: Wyjaśnij.
W jest lepsze niż z, ponieważ …: Oferuj osądy, a nawet opinie, gdzie to odpowiednie.
X w systemie y jest analogiczne do w w systemie z. Jednak …: Dostarcz kontekst, który pomaga czytelnikowi.
Niektórzy użytkownicy wolą w (ponieważ z). To może być dobre podejście, ale…: Rozważ alternatywy.
X współdziała z y w następujący sposób: …: Rozwiń wewnętrzne sekrety maszyny, aby pomóc zrozumieć, dlaczego coś robi to, co robi.

Analogia z jedzenia i gotowania¶

W 1984 Harold McGee opublikował On food and cooking.

Książka nie uczy, jak gotować cokolwiek. Nie zawiera przepisów (poza przykładami historycznymi) i nie jest dziełem referencyjnym. Zamiast tego umieszcza jedzenie i gotowanie w kontekście historii, społeczeństwa, nauki i technologii. Wyjaśnia na przykład, dlaczego robimy to, co robimy w kuchni i jak to się zmieniało.

Jest jasne, że nie jest to książka, którą czytalibyśmy podczas gotowania. Czytalibyśmy ją, gdy chcemy zastanowić się nad gotowaniem. Oświetla temat, przyjmując wiele różnych perspektyw na niego, rzucając światło z różnych kątów.

Po przeczytaniu książki takiej jak On food and cooking, nasze zrozumienie się zmienia. Nasza wiedza jest bogatsza i głębsza. To, czego się nauczyliśmy, może nie być od razu zastosowane następnym razem, gdy coś robimy w kuchni, ale zmieni to, jak myślimy o naszym rzemiośle, i wpłynie na naszą praktykę.