Fundamenty

Diátaxis jest skuteczny, ponieważ działa - zarówno użytkownicy, jak i twórcy mają lepsze doświadczenie z dokumentacją w wyniku tego. Ma sens i wydaje się właściwy.

Jednak to nie wystarczy, aby być pewnym Diátaxis jako teorii dokumentacji. Jako teoria, musi pokazać dlaczego działa. Musi pokazać, że jest jakiś powód, dla którego są dokładnie cztery rodzaje dokumentacji, a nie trzy lub pięć. Musi zademonstrować rygorystyczne myślenie i analizę oraz to, że opiera się na solidnej podstawie teoretycznej.

W przeciwnym razie będzie tylko kolejnym użytecznym heurystycznym podejściem, a najsilniejszym argumentem, jaki możemy wysunąć na jego korzyść, jest to, że wydaje się działać całkiem dobrze.

Dwa wymiary rzemiosła

Diátaxis opiera się na zasadzie, że dokumentacja musi służyć potrzebom jej użytkowników. Wiedza, jak to robić, oznacza zrozumienie, jakie są potrzeby użytkowników.

Użytkownik, którego potrzeby zaspokaja Diátaxis, to praktyk w dziedzinie umiejętności. Dziedzina umiejętności jest zdefiniowana przez rzemiosło - użycie narzędzia lub produktu jest rzemiosłem. Jest nim również cała dyscyplina lub zawód. Używanie języka programowania jest rzemiosłem, podobnie jak latanie konkretnym samolotem, lub nawet bycie pilotem w ogóle.

Zrozumienie potrzeb tych użytkowników oznacza z kolei zrozumienie istotnych cech rzemiosła lub umiejętności.

Działanie/poznanie

Umiejętność lub rzemiosło lub praktyka zawiera zarówno działanie (praktyczną wiedzę, wiedzę jak, co robimy), jak i poznanie (wiedzę teoretyczną, wiedzę że, co myślimy). Oba są całkowicie ze sobą związane, ale są odpowiednikami, całkowicie odrębnymi od siebie, dwoma różnymi aspektami tej samej rzeczy.

Nabycie/zastosowanie

Podobnie, relacja praktyka z jego praktyką jest taka, że jest to coś, co musi być zarówno nabyte, jak i zastosowane. Bycie „w pracy” (zajętym zastosowaniem umiejętności i wiedzy swojego rzemiosła) i bycie „w nauce” (zajętym nabywaniem ich) są ponownie odpowiednikami, odrębnymi, ale ściśle ze sobą związanymi.

Mapa terytorium

Daje nam to dwie wymiary umiejętności, które możemy rozłożyć na mapie - mapie terytorium rzemiosła:

Jest to kompletna mapa. Są tylko dwa wymiary, i nie tylko pokrywają całe terytorium, ale je definiują. Dlatego koniecznie są cztery ćwiartki, i nie mogłoby być trzech, lub pięciu. Nie jest to liczba arbitralna.

Pokazuje nam również jakości rzemiosła, które definiują każdą z nich. Gdy pomysł, że dokumentacja musi służyć potrzebom rzemiosła, jest zastosowany do tej mapy, ujawnia z kolei, czym dokumentacja musi być i co musi robić, aby wypełnić te obowiązki - w czterech odrębny sposobach.

Służenie potrzebom

Mapa terytorium rzemiosła jest tym, co daje nam znajomą mapę Diátaxis dokumentacji. Mapa jest w istocie odpowiedzią na pytanie: co musi robić dokumentacja, aby być zgodną z tymi jakościami umiejętności, i do jakiej potrzeby jest zorientowana w każdym przypadku?

Możemy zobaczyć, jak mapa dokumentacji odpowiada potrzebom wzdłuż tych dwóch wymiarów, każda potrzeba również zdefiniowana przez cechy jej ćwiartki na mapie.

potrzeba	zaspokojona w	użytkowniku	dokumentacji
uczenie się	tutoriale	nabywa swoje rzemiosło	informuje działanie
cele	przewodniki krok po kroku	stosuje swoje rzemiosło	informuje działanie
informacja	referencja	stosuje swoje rzemiosło	informuje poznanie
zrozumienie	wyjaśnienie	nabywa swoje rzemiosło	informuje poznanie

Mapa Diátaxis dokumentacji jest zapadającym w pamięć i przystępnym pomysłem. Ale mapa jest wiarygodna tylko wtedy, gdy odpowiednio opisuje rzeczywistość. Diátaxis opiera się na systematycznym opisie i analizie uogólnionych potrzeb użytkowników.

Dlatego tutoriale, przewodniki krok po kroku, referencje i wyjaśnienia Diátaxis są kompletnym wyliczeniem rodzajów dokumentacji, które służą praktykom w rzemiośle. Dlatego są tylko cztery rodzaje dokumentacji. Po prostu nie ma innego terytorium do pokrycia.