Diátaxis – dokumentacja idealna
TL;DR
Przetestowałem kilka frameworków do dokumentacji i żaden nie spełnił moich oczekiwań. Powód nie był w nich – był w budowie: wszystkie zaczynały od struktury i oczekiwały, że tekst się w nią wpasuje. Diátaxis zmienia to i zaczyna od pytania, po co ktoś sięgnie po tekst. Brak szablonu i sztywnych reguł – tekst sprawdza się dopiero po napisaniu, jak audyt. Efekt to płynność, która nie bierze się z znajomości reguł i schematów, tylko z naturalnego doświadczenia, które powstaje niemal organicznie.
CEL
Przetestowałem kilka frameworków do dokumentacji i każdy poległ na tym samym. Schemat był bardzo podobny za każdym razem – dopóki tekst pasował do danego frameworka, wszystko działało. Ale kiedy natrafiałem na zdanie, które nie pasowało do żadnej wytycznej, miałem dwie możliwości: wyrzucić tekst albo złamać zasadę.
Łamanie zasady okazywało się łatwiejsze i pozornie poprawne. Niestety, jak już raz złamałem zasadę, nie miałem powodu nie złamać jej ponownie. Robiłem to w dobrej wierze, za każdym razem przekonany, że to tylko wyjątek. Po kilku takich wyjątkach tekst był już na tyle zatruty, że przestawał być dokumentacją, a stawał się małym potworem Frankensteina – wszystko, wszędzie, naraz.
Takie podejście utwierdzało mnie w przekonaniu, że to wina frameworka i najlepszym rozwiązaniem będzie znalezienie kolejnego. Tak nie było. Problem był w moim podejściu: wprowadzałem strukturę i dopasowywałem do niej tekst. Jeżeli coś nie pasowało, trzeba było dopasowywać mocniej, aż zacznie pasować.
Na Diátaxis natrafiłem przypadkiem. Zainteresowało mnie, że nie zaczyna się od struktury, tylko od pytania, po co ktoś sięga po ten tekst, i dopiero odpowiedź wyznacza kierunek tekstu. Nie ma tu szablonu do wypełnienia, są kryteria, po których rozpoznaje się rodzaj tekstu, dla którego przewidziane są reguły mówiące, co ma w nim być. Płynność, która się pojawia w tekście, jest tego skutkiem: gdy każdy fragment tekstu robi jedną rzecz, tekst czyta się płynniej, a kolejne zdania płynnie się ze sobą łączą – tekst czyta się dobrze sam z siebie.
Celem tego artykułu jest wyjaśnienie, czym jest Diátaxis i jak taki efekt płynnego tekstu za pomocą tego frameworka można osiągnąć. Wprowadza on metodę rozpoznawania rodzaju tekstu, a następnie zasady, czego nie wolno w nim zastosować. Dzięki temu nie mamy tutaj sztywnego szablonu do wypełnienia, a model, który działa jak audyt: wskazuje problemy do rozwiązania, co poprawia jakość tekstu.
ROZWIĄZANIE
Nie będę opisywał tutaj całego frameworka, tylko skupię się na 2 filarach, które wpłynęły na mnie najbardziej: wyjaśnienie i jakość.
Wyjaśnienie
Zacznijmy od pytania, które przez lata wydawało mi się stratą czasu: dlaczego to działa?
Wiedziałem, jak coś zrobić, ale nie rozumiałem, dlaczego to, co robię, działa. Nie było powodu pytać, dlaczego działa – wiedza teoretyczna w tym układzie wygląda jak coś, co przynosi tylko stratę.
Kłopot zaczyna się wtedy, kiedy pojawia się problem, którego dokumentacja nie przewidziała. Teoria nie przyspiesza pracy z dokumentacją, przyspiesza to, co się dzieje, gdy pierwszy raz coś nie wyjdzie w przewidzianym wariancie. Pojawia się naturalny problem – jakie zachować proporcje?
Diátaxis rozwiązuje tę kwestię poprzez zaprzeczenie intuicji, czyli podział czytelników i zaadresowanie do konkretnej osoby – określamy, czy czytać to będzie inżynier, programista czy księgowy.
Diátaxis proponuje, aby nie iść tą drogą i zadać sobie pytanie „po co ktoś sięga po tę dokumentację”. Odpowiedź jest jedna i konkretna, niezależnie od osoby czytającej. Stąd należy pamiętać o tej bardzo prostej zasadzie, która jest taka trudna do implementacji – mieć cały czas z tyłu głowy pytanie „dlaczego tak, a nie inaczej”.
Tutaj pojawia się ciekawa kwestia – w wyjaśnieniu wolno mieć opinię, co wydaje się nieintuicyjne. Całość opiera się na tym, że jeżeli umieścimy opinię, ale bez alternatywy, to powstaje reklama, ale kiedy umieścimy opinię z alternatywą i to taką z uzasadnieniem, to tworzymy podwaliny pod dyskusję, co jest już akceptowalne, a nawet mocno dynamizujące tekst.
Jakość
Diátaxis jest frameworkiem, który porządkuje dokumentację, za punkt odniesienia biorąc sobie jakość.
Od razu pojawia się kłopot, bo o ile możemy się zgodzić z tym, że każdy chciałby dokumentację dobrej jakości, to kiedy przychodzi do zdefiniowania, co ma być tą dobrą jakością – tutaj już pojawia się problem, bo nikt nie umie powiedzieć, co to znaczy. Doprowadza to do efektu, że zaczynamy się tego bać i zostawiamy to nieokreślone, a jak wiadomo, nie da się osiągnąć celu, który nie jest zdefiniowany.
Diátaxis naprawia to przez rozbicie jakości na dwa rodzaje: jakość funkcjonalną i jakość głęboką.
Funkcjonalna jest łatwa do zmierzenia i określenia. Jest to wymierne. Przy czym cechy te są od siebie niezależne – tekst może być precyzyjny i niedokończony.
Głęboka nie jest łatwo mierzalna i trudna do zdefiniowania, ale mimo to jest do rozpoznania. Zdefiniowanie pięknej dokumentacji nie jest łatwe, a czasami wręcz niemożliwe, ale po przeczytaniu dokumentacji każdy z nas potrafi określić, czy była ona piękna, czy nie.
Diátaxis proponuje rozwiązanie tego problemu przez ograniczenie – wprowadzenie skończonych i jasnych ram, które jasno ograniczają tekst, ale doprowadzają do tego, że możemy zamknąć jakość funkcjonalną i przejść do jakości głębokiej.
I teraz najważniejsza rzecz, którą wprowadza Diátaxis, to brak zasad. Całość jest banalnie prosta – piszemy dokumentację w sposób naturalny, intuicyjny, przez co powstaje ona w sposób wręcz organiczny, i dopiero na końcu przepuszczamy ją przez framework, który wskaże i wypunktuje wszelkie problemy i niedoskonałości, jakie wymagają naprawy. Jest to z jednej strony bardzo trudny sposób działania, ponieważ musimy wprowadzać w kółko poprawki, pracując w pętli pisanie → poprawki, ale w tym cyklu pojawia się bardzo ważny element: całość nauki frameworka powstaje naturalnie, nie poprzez sztywne reguły, tylko organicznie, wręcz namacalnie.
PODSUMOWANIE
Zaczynałem od pytania, który framework wybrać. Po drodze okazało się, że pytanie było źle postawione. Wszystkie poprzednie działały tak samo: najpierw struktura, potem dopasowanie tekstu. Diátaxis odwraca tę kolejność i to jest cała różnica.
Można powiedzieć, że Diátaxis nauczył mnie wyjścia poza schematy i brania większej odpowiedzialności za tekst – to nie jest tak, że schemat był zły, tylko moje umiejętności były niewystarczające lub założenia.
Myślę, że to najważniejszy wniosek: nie zasłanianie się schematami, tylko branie odpowiedzialności za to, co się wykonuje.
Link do framework: diataxis.fr