Diátaxis¶
Systematyczne podejście do tworzenia dokumentacji technicznej.
Diátaxis to sposób myślenia o dokumentacji i jej tworzeniu.
Przepisuje podejścia do treści, architektury i formy, które wynikają z systematycznego podejścia do zrozumienia potrzeb użytkowników dokumentacji.
Diátaxis identyfikuje cztery odrębne potrzeby i odpowiadające im formy dokumentacji - tutoriale, przewodniki krok po kroku, techniczne referencje i wyjaśnienia. Umieszcza je w systematycznym związku i proponuje, aby dokumentacja sama w sobie była zorganizowana wokół struktur tych potrzeb.
Diátaxis rozwiązuje problemy związane z treścią dokumentacji (co pisać), stylem (jak to pisać) i architekturą (jak ją organizować).
Oprócz służenia użytkownikom dokumentacji, Diátaxis ma wartość dla twórców i opiekunów dokumentacji. Jest lekki, łatwy do zrozumienia i prosty w zastosowaniu. Nie narzuca ograniczeń implementacyjnych. Wprowadza aktywną zasadę jakości do dokumentacji, która pomaga opiekunom efektywnie myśleć o swojej pracy.
Spis treści¶
Najlepszym sposobem rozpoczęcia pracy z Diátaxis jest zastosowanie go po przeczytaniu krótkiego wprowadzenia.
Te strony pomogą od razu zrozumieć to podejście w sposób konkretny.
Ta sekcja bada teorię i zasady Diátaxis głębiej i przedstawia zrozumienie potrzeb, które są jego podstawą.
Diátaxis jest sprawdzony w praktyce. Jego zasady zostały z powodzeniem przyjęte w setkach projektów dokumentacyjnych.
Diátaxis pozwolił nam zbudować wysokiej jakości zestaw wewnętrznej dokumentacji, którą uwielbiają nasi użytkownicy, a nasi współtwórcy uwielbiają do niej dodawać.
—Greg Frileux, Vonage
W Gatsby niedawno zreorganizowaliśmy naszą otwartoźródłową dokumentację, a framework Diátaxis był naszym głównym źródłem przez cały projekt. Cztery ćwiartki pomogły nam priorytetyzować cel użytkownika dla każdego typu dokumentacji. Przebudowując naszą dokumentację wokół frameworka Diátaxis, ułatwiliśmy użytkownikom odkrywanie zasobów, których potrzebują, gdy ich potrzebują.
Podczas przeprojektowywania dokumentacji dla deweloperów Cloudflare, Diátaxis stał się naszym przewodnikiem dla architektury informacji. Gdy nie byliśmy pewni, gdzie nowy kawałek treści powinien się znaleźć, konsultowaliśmy framework. Nasza dokumentacja jest teraz jaśniejsza niż kiedykolwiek, zarówno dla czytelników, jak i współtwórców.