Różnica między referencją a wyjaśnieniem¶

Wyjaśnienie i referencja należą do teoretycznej części mapy Diátaxis - nie zawierają kroków, które mają prowadzić czytelnika, zawierają wiedzę teoretyczną.

Różnica między nimi to - podobnie jak w różnicy między tutorialami a przewodnikami krok po kroku - różnica między nabyciem umiejętności i wiedzy, a jej zastosowaniem. Innymi słowy, to rozróżnienie między nauką a pracą.

Proste rozróżnienie, zazwyczaj¶

Zazwyczaj dość łatwo jest rozpoznać, czy mamy do czynienia z jednym, czy z drugim. Referencja, jako forma pisania, jest dobrze rozumiana; jest używana w rozróżnieniach, które wprowadzamy od wczesnego wieku.

Dodatkowo, przykłady pisania są same w sobie często wyraźnie jednym lub drugim. Tabela pływów, z jej tabelami liczb, jest wyraźnie materiałem referencyjnym. Artykuł, który wyjaśnia dlaczego występują pływy i jak się zachowują, jest oczywiście wyjaśnieniem.

Istnieją dobre reguły kciuka:

Jeśli jest nudne i niezapadające w pamięć to prawdopodobnie referencja.
Listy rzeczy (takie jak klasy lub metody lub atrybuty), i tabele informacji, zazwyczaj okażą się należeć do referencji.
Z drugiej strony jeśli możesz sobie wyobrazić czytanie czegoś w wannie, prawdopodobnie jest to wyjaśnienie (nawet jeśli tak naprawdę nie ma mowy o tym, co ludzie mogą czytać w wannie).

Wyobraź sobie, że pytasz przyjaciela, podczas spaceru lub przy drinku, Czy możesz mi więcej powiedzieć o 1? - odpowiedź lub dyskusja, która następuje, najprawdopodobniej będzie wyjaśnieniem tego.

… ale intuicja nie jest wystarczająco niezawodna¶

Zazwyczaj możemy bezpiecznie polegać na intuicji, aby zarządzać rozróżnieniem między referencją a wyjaśnieniami. Ale tylko zazwyczaj - ponieważ również dość łatwo jest przejść z jednej formy do drugiej.

Zwykle dzieje się to podczas pisania materiału referencyjnego, który zaczyna się rozrastać. Na przykład całkiem rozsądne jest włączenie ilustracyjnych przykładów do referencji (podobnie jak encyklopedia może zawierać ilustracje) - ale przykłady są fajnymi rzeczami do rozwijania, i może być kuszące rozwijać je w wyjaśnienie (używając ich, aby powiedzieć dlaczego, lub co jeśli, lub jak to się stało).

W rezultacie często znajduje się materiał wyjaśniający rozsypany w referencji. To szkodzi referencji, przerywanej i zasłanianej dygresjami. Ale szkodzi to również wyjaśnieniu, ponieważ nie jest ono dozwolone, aby rozwijać się odpowiednio i robić swoją własną pracę.

Praca i nauka¶

Prawdziwy test, jeśli mamy wątpliwości, czy coś powinno być referencją czy wyjaśnieniem, to: czy to coś, do czego ktoś by sięgnął podczas pracy, czyli podczas rzeczywistego wykonywania czegoś, realizacji zadania? Czy to coś, czego potrzebowaliby, gdy odeszli od pracy i chcieli o tym pomyśleć?

Są to dwa bardzo fundamentalnie różne potrzeby czytelnika, które odzwierciedlają, jak w danym momencie czytelnik stoi w relacji do rzemiosła w kwestii, w relacji pracy lub nauki.

Referencja to coś, czego użytkownik potrzebuje, aby pomóc zastosować wiedzę i umiejętność, podczas gdy pracuje.

Wyjaśnienie to coś, do czego ktoś sięgnie, aby pomóc mu nabyć wiedzę i umiejętność - nauka.

Zrozumienie tych dwóch relacji i odpowiadanie na potrzeby w nich jest kluczem do tworzenia skutecznej referencji i wyjaśnienia.