Zacznij tutaj - Diátaxis w pięć minut¶

Nie musisz czytać wszystkiego na tej stronie, aby zrozumieć Diátaxis, lub aby zacząć używać go w praktyce. W rzeczywistości zalecam, abyś tego nie robił. Najlepszym sposobem rozpoczęcia pracy z Diátaxis jest zastosowanie go - do czegoś, choćby małego.

Przeczytaj tę stronę dla krótkiego wprowadzenia. Każda sekcja zawiera linki do bardziej szczegółowego materiału; odwołuj się do niego, gdy go potrzebujesz - gdy jesteś w trakcie pracy, lub zastanawiasz się nad problemami związanymi z dokumentacją, które napotkałeś.

Cztery rodzaje dokumentacji¶

Podstawowa idea Diátaxis jest taka, że istnieją fundamentalnie cztery identyfikowalne rodzaje dokumentacji, które odpowiadają na cztery różne potrzeby. Cztery rodzaje to: tutoriale, przewodniki krok po kroku, referencje i wyjaśnienia. Każdy z nich ma inny cel i musi być pisany w inny sposób.

Tutoriale¶

Tutorial to lekcja, która prowadzi ucznia za rękę przez doświadczenie edukacyjne. Tutorial jest zawsze praktyczny: użytkownik robi coś, pod kierunkiem instruktora. Tutorial jest zaprojektowany wokół spotkania, które uczeń może zrozumieć, w którym instruktor jest odpowiedzialny za bezpieczeństwo i sukces ucznia.

Lekcja jazdy jest dobrym przykładem tutorialu. Celem lekcji jest rozwinięcie umiejętności i pewności siebie u ucznia, a nie dotarcie z punktu A do punktu B. Przykładem oprogramowania może być: Stwórzmy prostą grę w Pythonie.

Użytkownik uczy się poprzez działanie, a nie dlatego, że ktoś próbował go nauczyć.

W dokumentacji szczególną trudnością jest to, że instruktor jest skazany na nieobecność i nie może monitorować uczącego się ani korygować jego błędów. Instruktor musi w jakiś sposób znaleźć sposób, aby być obecnym wyłącznie poprzez instrukcje pisemne.

Przewodniki krok po kroku¶

Poradnik krok po kroku dotyczy rzeczywistego celu lub problemu w świecie, zapewniając praktyczne wskazówki, które pomagają użytkownikowi znajdującemu się w tej sytuacji.

Poradnik krok po kroku zawsze kierowany jest do użytkownika już kompetentnego, od którego oczekuje się, że będzie potrafił wykorzystać przewodnik, aby pomóc mu w wykonaniu pracy. W przeciwieństwie do samouczka, poradnik krok po kroku koncentruje się na pracy a nie na nauce.

Poradnik krok po kroku może dotyczyć: Jak przechowywać taśmę filmową z nitrocelulozy (w fotografii filmowej) lub Jak skonfigurować profilowanie ramek (w oprogramowaniu). Albo nawet: Rozwiązywanie problemów z wdrażaniem.

Referencje¶

Przewodniki referencyjne zawierają opis techniczny - fakty - których użytkownik potrzebuje, aby wykonywać czynności poprawnie: dokładne, kompletne i wiarygodne informacje, wolne od rozproszenia i interpretacji. Zawierają wiedzę propozycyjną lub teoretyczną, a nie przewodniki po działaniu.

Podobnie jak poradnik krok po kroku, dokumentacja referencyjna służy użytkownikowi, który jest w trakcie pracy, i to od użytkownika zależy, czy jest na tyle kompetentny, aby poprawnie ją zinterpretować i wykorzystać.

Materiał referencyjny jest neutralny. Nie zajmuje się tym, co robi użytkownik. Mapa morska mogłaby być używana przez nawigatora statku do wyznaczenia kursu, ale równie dobrze przez sędziego śledczego.

W miarę możliwości struktura dokumentacji referencyjnej powinna odzwierciedlać strukturę lub architekturę tego, co opisuje - tak jak mapa. Jeśli metoda jest częścią klasy należącej do określonego modułu, to powinniśmy oczekiwać, że ta sama relacja będzie widoczna w dokumentacji.

Wyjaśnienie¶

Przewodniki wyjaśniające zapewniają kontekst i tło. Służą potrzebie zrozumienia i umieszczenia rzeczy w szerszej perspektywie. Wyjaśnienie łączy rzeczy ze sobą i pomaga odpowiedzieć na pytanie dlaczego?

Wyjaśnienie często musi krążyć wokół swojego tematu i podchodzić do niego z różnych stron. Może zawierać opinie i przyjmować perspektywy.

Podobnie jak dokumentacja referencyjna, wyjaśnienie należy do dziedziny wiedzy propozycyjnej, a nie działania. Jednak jego celem jest służenie studiom użytkownika - tak jak w przypadku samouczków - a nie jego pracy.

Często autorzy samouczków, którzy są zaniepokojeni, że ich uczniowie powinni wiedzieć rzeczy, przeładowują swoje samouczki rozpraszającym i nieprzydatnym wyjaśnieniem. O wiele bardziej pomocne byłoby podanie uczącemu się minimalnego wyjaśnienia (Tutaj używamy HTTPS, ponieważ jest bezpieczniejsze) i następnie podanie linku do artykułu szczegółowego (Bezpieczna komunikacja przy użyciu szyfrowania HTTPS) na czas, gdy użytkownik będzie na to gotowy.

Mapa Diátaxis¶

Cztery rodzaje dokumentacji i relacje między nimi można podsumować za pomocą mapy Diátaxis.

Diátaxis to nie tylko lista czterech różnych rzeczy, ale koncepcyjne ułożenie ich. Pokazuje, jak cztery rodzaje dokumentacji są ze sobą powiązane i jak są od siebie odrębne.

Przekraczanie lub zacieranie granic opisanych na mapie znajduje się w centrum ogromnej liczby problemów w dokumentacji.

Kompas Diátaxis¶

Jak możesz zobaczyć na mapie:

samouczki i poradniki krok po kroku dotyczą tego, co użytkownik robi (działanie)
dokumentacja referencyjna i wyjaśnienia dotyczą tego, co użytkownik wie (poznanie)

Z drugiej strony:

tutoriale i wyjaśnienia służą zdobywaniu umiejętności (proces nauki użytkownika)
poradniki krok po kroku i dokumentacja referencyjna służą stosowaniu umiejętności (praca użytkownika)

Ale mapa nie mówi ci, co robić - jest dokumentacją referencyjną. Aby pokierować działaniem, potrzebne jest inne narzędzie, w tym przypadku rodzaj kompasu Diátaxis.

Kompas jest przydatny na dwa różne sposoby.

Podczas tworzenia dokumentacji pomaga wyjaśnić własne intencje i upewnić się, że robisz to, co myślisz, że robisz.

Podczas przeglądania dokumentacji pomaga zrozumieć, co się w niej dzieje, i sprawia, że problemy stają się widoczne.

Kompas nie jest tak przyciągający wzrok jak mapa, ale gdy jesteś w trakcie pracy i zastanawiasz się nad problemem związanym z dokumentacją, to właśnie on pomoże ci ruszyć do przodu.

Jeśli treść…	…i służy użytkownikowi…	…to musi należeć do…
informuje działanie	nabycie umiejętności	tutorial
informuje działanie	zastosowanie umiejętności	przewodnik krok po kroku
informuje poznanie	zastosowanie umiejętności	referencja
informuje poznanie	nabycie umiejętności	wyjaśnienie

Praca¶

Istnieje bardzo prosty przepływ pracy dla Diátaxis.

Rozważ to, co widzisz w dokumentacji, przed sobą w tej chwili (co może być dosłownie niczym, jeśli jeszcze nie zacząłeś).
Zapytaj: Czy jest jakiś sposób, w jaki można by to poprawić?
Zdecyduj na jedną rzecz, którą mógłbyś zrobić z nią w tej chwili, choćby najmniejszą, która by ją poprawiła.
Zrób to.

A potem powtórz.

To wszystko.

Rób, co chcesz¶

Możesz robić z Diátaxis, co chcesz. Nie musisz w nią wierzyć i nie ma żadnego egzaminu. Jest to całkowicie pragmatyczne podejście. Myślę, że jest prawdziwa, ale ważne jest to, że naprawdę pomaga ludziom tworzyć lepszą dokumentację. Jeśli znajdziesz jeden pomysł lub spostrzeżenie w niej, które wydaje się wartościowe, weź je sobie.

Istnieje obszernie rozwinięta teoria wokół Diátaxis, ale nie musisz się z nią zgadzać, ani nawet o niej czytać. Diátaxis nie wymaga zobowiązania do jej kontynuowania do końca.

Możesz zrobić tylko jedną rzecz, w tej chwili, i nawet jeśli potem już nic więcej nie zrobisz, to przynajmniej dokonasz tej jednej poprawy. (W praktyce okaże się, że każda rzecz, którą zrobisz, da ci wskazówkę, co zrobić następnie - wystarczy, że będziesz je robić).

Zacznij¶

W tym momencie przeczytałeś wszystko, co potrzebujesz, aby zacząć korzystać z Diátaxis.

Możesz czytać więcej, jeśli chcesz, i ostatecznie prawdopodobnie powinieneś, ale największą wartość z przewodnika na tej stronie uzyskasz, gdy zwrócisz się do niego z problemem lub pytaniem. Wtedy ożywa.