Diátaxis jako przewodnik po pracy

Oprócz dostarczania przewodnika po zawartości dokumentacji, Diátaxis jest również przewodnikiem po procesie i wykonaniu dokumentacji.

Większość osób pracujących nad dokumentacją techniczną musi podejmować decyzje dotyczące sposobu pracy, podczas gdy pracują. W niektórych kontekstach dokumentacja musi być dostarczona raz, kompletna i w swojej ostatecznej formie, ale częściej jest to ciągły projekt, na przykład rozwijany równolegle z produktem, który sam ewoluuje i rozwija się. Wiele osób pracujących nad dokumentacją doświadcza również odpowiedzialności za poprawianie lub nawet naprawianie zbioru dokumentacji.

Diátaxis oferuje podejście do pracy, które stoi w sprzeczności z wieloma powszechnie akceptowanymi poglądami w dokumentacji. W szczególności zniechęca do planowania i odgórnych przepływów pracy, preferując zamiast tego małe, elastyczne iteracje, z których wyłaniają się ogólne wzorce.

Używaj Diátaxis jako przewodnika, a nie planu

Diátaxis opisuje kompletny obraz dokumentacji. Jednak struktura, którą proponuje, nie jest przeznaczona jako plan, coś, co musisz ukończyć w swojej dokumentacji. To przewodnik, mapa, która pomaga sprawdzić, czy jesteś we właściwym miejscu i idziesz we właściwych kierunkach.

Celem Diátaxis jest dostarczenie ci sposobu myślenia i rozumienia twojej dokumentacji, abyś mógł lepiej zrozumieć, co ona robi i co próbujesz z nią zrobić. Dostarcza narzędzia, które pomagają ocenić ją, zidentyfikować, gdzie leżą jej problemy, i osądzić, co możesz zrobić, aby ją poprawić.

Nie martw się o strukturę

Chociaż struktura jest kluczowa dla dokumentacji, korzystanie z Diátaxis oznacza niepoświęcanie energii na poprawne ustrukturyzowanie jej.

Jeśli będziesz nadal podążać za wskazówkami, które dostarcza Diátaxis, twoja dokumentacja ostatecznie przyjmie strukturę Diátaxis - ale przyjmie tę formę ponieważ została poprawiona. To nie jest tak, że struktura musi być narzucona na dokumentację, aby ją poprawić.

Rozpoczęcie pracy z Diátaxis nie wymaga od ciebie myślenia o podziale dokumentacji na cztery sekcje. Z pewnością nie oznacza to, że powinieneś tworzyć puste struktury dla tutoriali/przewodników krok po kroku/referencji/wyjaśnień. Nie rób tego. To okropne.

Zamiast tego, postępując zgodnie z przepływem pracy opisanym w następnych dwóch sekcjach, wprowadzaj zmiany, gdzie widzisz możliwości poprawy zgodnie z zasadami Diátaxis, tak aby dokumentacja zaczęła przybierać pewien kształt. W pewnym momencie wprowadzone zmiany będą wydawać się wymagać, abyś przeniósł materiał pod określoną sekcją Diátaxis - i w ten sposób uformuje się twoja struktura najwyższego poziomu. Innymi słowy, Diátaxis zmienia strukturę twojej dokumentacji od wewnątrz.

Pracuj krok po kroku

Diátaxis zdecydowanie przepisuje strukturę, ale niezależnie od stanu twojej istniejącej dokumentacji - nawet jeśli jest kompletnym bałaganem według wszelkich standardów - zawsze możesz ją poprawić, iteracyjnie.

Naturalne jest chęć ukończenia dużych partii pracy przed ich opublikowaniem, aby za każdym razem mieć coś znaczącego do pokazania. Unikaj tej pokusy - każdy krok we właściwym kierunku jest wart natychmiastowego opublikowania.

Chociaż Diátaxis ma dostarczyć duży obraz dokumentacji, nie próbuj pracować nad dużym obrazem. To zarówno niepotrzebne, jak i niewłaściwe. Diátaxis jest zaprojektowana, aby kierować małymi krokami; kontynuuj wykonywanie małych kroków, aby dotrzeć tam, gdzie chcesz.

Po prostu coś zrób

Jeśli sprzątasz ogromny bałagan, pokusa polega na tym, aby wszystko zburzyć i zacząć od nowa. Ponownie, unikaj tego. Jeśli chodzi o poprawę dokumentacji zgodnie z Diátaxis, nie jest konieczne szukanie rzeczy do poprawy. Zamiast tego, najlepszym sposobem na zastosowanie Diátaxis jest:

Wybierz coś - dowolny fragment dokumentacji. Jeśli nie masz jeszcze czegoś, co chcesz naprawić, nie szukaj wyraźnych problemów. Po prostu spójrz na to, co masz przed sobą w danym momencie: plik, w którym jesteś, ostatnią przeczytaną stronę - to nie ma znaczenia. Jeśli nie ma takiego, wybierz coś losowo.

Oceń to. Następnie rozważ ten element krytycznie. Najlepiej, jeśli jest to coś małego, nie większego niż strona - a jeszcze lepiej, nawet mniejszego, akapit lub zdanie. Poddaj to próbie zgodnie ze standardami, które przepisuje Diátaxis: Jaką potrzebę użytkownika reprezentuje ten element? Jak dobrze służy tej potrzebie? Co można dodać, przenieść, usunąć lub zmienić, aby lepiej służył tej potrzebie? Czy jego język i logika spełniają wymagania tego trybu dokumentacji?

Zdecyduj, co zrobić. Zdecyduj, na podstawie odpowiedzi na te pytania: Jakie pojedyncze następne działanie przyniesie natychmiastową poprawę tutaj?

Zrób to. Wykonaj to pojedyncze działanie i uznaj je za zakończone - tzn. opublikuj je, lub przynajmniej zatwierdź zmianę. Nie czuj, że musisz zrobić coś więcej, aby dokonać wartościowej poprawy.

A następnie wróć do początku cyklu.

Praca w ten sposób pomaga zmniejszyć stres związany z jednym z najbardziej paraliżujących i kłopotliwych aspektów pracy autora dokumentacji: wymyślaniem, co robić. Utrzymuje przepływ pracy we właściwym kierunku, zawsze w stronę pożądanego celu, bez konieczności wydatkowania energii na plan.

Pozwól swojej pracy rozwijać się organicznie

Istnieje silna pokusa, aby pracować w cyklu planowania i wykonania, aby dążyć do wyników. Ale to nie jedyny sposób, i często istnieją lepsze sposoby pracy z dokumentacją.

Dobrze uformowany wzrost organiczny

Dobrym modelem dla dokumentacji jest dobrze uformowany wzrost organiczny, który dostosowuje się do warunków zewnętrznych. Wzrost organiczny zachodzi na poziomie komórkowym. Struktura całego organizmu jest zagwarantowana przez zdrowy rozwój komórek, zgodnie z zasadami odpowiednimi dla każdego rodzaju komórki. To nie odwrotnie, że struktura jest narzucana organizmowi z góry lub z zewnątrz. Dobra struktura rozwija się od wewnątrz.

Ilustracja copyright Linette Voller 2021, reprodukowana za zgodą.

To samo dotyczy dokumentacji: przestrzegając zasad, które przepisuje Diátaxis, Twoja dokumentacja osiągnie zdrową strukturę, ponieważ jej wewnętrzne składniki same są dobrze uformowane - podobnie jak żywy organizm, zbuduje się od wewnątrz na zewnątrz, komórka po komórce.

Kompletne, nie skończone

Rozważ roślinę. Jako żywy, rozwijający się organizm, roślina jest nigdy nie skończona - zawsze może dalej się rozwijać, przejść do następnego etapu wzrostu i dojrzałości. Ale, na każdym etapie swojego rozwoju, od nasiona do w pełni dojrzałego drzewa, jest zawsze kompletna - nigdy nie brakuje jej czegoś. W każdym momencie jest w stanie odpowiednim do swojego etapu rozwoju.

Podobnie dokumentacja również nigdy nie jest skończona, ponieważ zawsze musi dostosowywać się i zmieniać wraz z produktem i potrzebami użytkowników, i zawsze może być dalej rozwijana i ulepszana.

Ale zawsze może być kompletna: użyteczna dla użytkowników, odpowiednia do swojego obecnego etapu rozwoju, i w zdrowym stanie strukturalnym, gotowa przejść do następnego etapu.