W kierunku teorii jakości w dokumentacji¶
Diátaxis to podejście do jakości w dokumentacji.
„Jakość” to słowo, któremu grozi utrata części znaczenia; to coś, z czym wszyscy się zgadzamy, ale rzadko ryzykujemy próbę opisania w jakikolwiek rygorystyczny sposób. Chcemy jakości w naszej dokumentacji, ale znacznie rzadziej określamy, co dokładnie mamy na myśli.
Mimo to, możemy zazwyczaj wskazać przykłady „wysokiej jakości dokumentacji”, gdy zostaniemy o to poproszeni, i możemy zidentyfikować uchybienia w jakości, gdy je widzimy - i więcej niż to, często zgadzamy się, gdy to robimy. To sugeruje, że nadal mamy użyteczne pojęcie jakości.
Podążając za jakością w dokumentacji, pomaga to uczynić to uchwycenie pewniejszym, poświęcając trochę uwagi - tutaj, próbując doprecyzować nasze uchwycenie przez postawienie rozróżnienia między jakością funkcjonalną a jakością głęboką.
Jakość funkcjonalna¶
Potrzebujemy, aby dokumentacja spełniała standardy dokładności, kompletności, spójności, użyteczności, precyzji i tak dalej. Możemy nazwać te aspekty jej jakości funkcjonalnej. Dokumentacja, która nie spełnia któregokolwiek z nich, nie spełnia jednej ze swoich kluczowych funkcji.
Te właściwości jakości funkcjonalnej są od siebie niezależne. Dokumentacja może być dokładna, ale niekompletna. Może być kompletna, ale niedokładna i niespójna. Może być dokładna, kompletna, spójna i jednocześnie bezużyteczna.
Osiągnięcie jakości funkcjonalnej oznacza spełnienie wysokich, mierzalnych obiektywnie standardów w wielu niezależnych wymiarach, konsekwentnie. Wymaga to dyscypliny i uwagi na szczegóły, oraz wysokiego poziomu umiejętności technicznych.
Aby utrudnić twórcy dokumentacji, każda porażka w spełnieniu wszystkich tych standardów jest łatwo dostrzegalna dla użytkownika.
Jakość głęboka¶
Istnieją inne cechy, które możemy nazwać jakością głęboką.
Jakość funkcjonalna nie wystarcza, ani nawet nie jest satysfakcjonująca sama w sobie jako ambicja. Prawdziwa doskonałość w dokumentacji implikuje cechy jakości, które nie są zawarte w dokładności, kompletności itp.
Pomyśl o cechach takich jak:
dobre samopoczucie podczas używania
posiadanie płynności
dopasowanie do ludzkich potrzeb
bycie pięknym
przewidywanie użytkownika
W przeciwieństwie do cech jakości funkcjonalnej, nie można ich sprawdzić ani zmierzyć, ale nadal można je wyraźnie zidentyfikować. Gdy się z nimi spotykamy, zwykle (nie zawsze, bo musimy być do tego zdolni) rozpoznajemy je.
Są to cechy jakości głębokiej.
Jaka jest różnica?¶
Aspekty jakości głębokiej wydają się być naprawdę odrębne w rodzaju od cech jakości funkcjonalnej.
Dokumentacja może spełniać wszystkie wymagania jakości funkcjonalnej i nadal nie wykazywać jakości głębokiej. Istnieje wiele przykładów dokumentacji, która jest dokładna i spójna (i nawet bardzo użyteczna), ale która jest również niezgrabna i nieprzyjemna w użyciu.
Zauważalne jest również, że podczas gdy cechy jakości funkcjonalnej, takie jak kompletność i dokładność, są niezależne od siebie, te jakości głębokiej są trudne do rozdzielenia. Posiadanie płynności i przewidywanie użytkownika to aspekty każdego z nich - są wzajemnie zależne. Trudno sobie wyobrazić, jak coś mogłoby dobrze się używać bez dopasowania do naszych potrzeb.
Aspekty jakości funkcjonalnej można zmierzyć - dosłownie, liczbami, w niektórych przypadkach (rozważ kompletność). To oczywiście nie jest możliwe z jakościami takimi jak posiadanie płynności. Zamiast tego, takie jakości można tylko badać, wypytywać. Zamiast brać pomiary, musimy dokonywać osądów.
Jakość funkcjonalna jest obiektywna - należy do świata. Dokładność dokumentacji oznacza stopień, w jakim odpowiada ona światu, który próbuje opisać. Jakość głęboka nie może być ustalona przez przyłożenie czegoś do świata. Jest subiektywna, co oznacza, że możemy ją ocenić tylko w świetle potrzeb podmiotu doświadczenia, człowieka.
I, jakość głęboka jest warunkowa względem jakości funkcjonalnej. Dokumentacja może być dokładna i kompletna i spójna bez bycia naprawdę doskonałą - ale nigdy nie będzie miała jakości głębokiej bez bycia dokładną i kompletną i spójną. Żaden użytkownik dokumentacji nie doświadczy jej jako pięknej, jeśli jest niedokładna, lub nie będzie cieszył się tym, jak przewiduje ich potrzeby, jeśli jest niespójna. W momencie, gdy napotkamy takie uchybienia, doświadczenie dokumentacji jest przyćmione.
Na koniec, wszystkie cechy jakości funkcjonalnej wydają się nam, jako twórcom dokumentacji, jako obciążenia i ograniczenia. Każda z nich reprezentuje test lub wyzwanie, któremu możemy nie sprostać. Lub, nawet jeśli spełniliśmy jeden teraz, nigdy nie możemy odpocząć, ponieważ kolejne wydanie lub aktualizacja oznacza, że będziemy musieli sprawdzić naszą pracę jeszcze raz, względem rzeczy, którą dokumentujemy. Cechy takie jak przewidywanie potrzeb lub płynność, z drugiej strony, reprezentują wyzwolenie, pracę kreatywności lub smaku. Aby osiągnąć jakość funkcjonalną w naszej pracy, musimy dostosować się do ograniczeń; aby osiągnąć jakość głęboką, musimy wymyślić.
Jakość funkcjonalna |
Jakość głęboka |
|---|---|
niezależne cechy |
wzajemnie zależne cechy |
obiektywna |
subiektywna |
mierzona względem świata |
oceniana względem człowieka |
warunek jakości głębokiej |
warunkowa względem jakości funkcjonalnej |
aspekty ograniczenia |
aspekty wyzwolenia |
Jak rozpoznajemy jakość głęboką¶
Rozważ, jak oceniamy jakość, powiedzmy, odzieży. Ubrania muszą mieć jakość funkcjonalną (muszą odpowiednio nas ogrzewać i chronić przed deszczem, wytrzymywać noszenie). Te rzeczy są obiektywnie mierzalne. Nie trzeba dużo wiedzieć o ubraniach, aby ocenić, jak dobrze spełniają te funkcje. Jeśli woda dostanie się do środka, lub ubranie się rozpadnie - brakuje mu jakości.
Istnieją inne cechy jakości w odzieży, których nie można po prostu mierzyć obiektywnie, a aby rozpoznać te cechy, potrzebujemy zrozumienia odzieży. Jakość materiałów lub wykonania nie zawsze jest od razu oczywista. Umiejętność oceny, że dana część odzieży dobrze się układa, dobrze się porusza lub została precyzyjnie ukształtowana, wymaga rozwinięcia przynajmniej podstawowego wyczucia tych rzeczy. I to są jej cechy jakości głębokiej.
Ale: nawet ktoś, kto nie potrafi rozpoznać, lub nie rozumie, tych cech - kto nie może powiedzieć co w nich jest dobre - może bardzo dobrze rozpoznać że odzież jest doskonała, ponieważ dobrze się w niej czuje, ponieważ taka jest, że chce ją nosić. Nie jest wymagana żadna ekspertyza, aby zdać sobie sprawę, że odzież jest wygodna lub niewygodna podczas poruszania się w niej, że dobrze pasuje i porusza się z tobą. Twoje ciało to wie.
I tak samo jest w dokumentacji. Być może trzeba być znawcą, aby rozpoznać co sprawia, że niektóre dokumentacje są doskonałe, ale to nie jest konieczne, aby móc stwierdzić że jest doskonała. Dobra dokumentacja dobrze się używa; czujesz przyjemność i satysfakcję, gdy z niej korzystasz - czuje się, jakby pasowała i poruszała się z tobą.
Użytkownicy naszej dokumentacji mogą lub nie mieć zrozumienia, aby powiedzieć, dlaczego jest dobra, lub gdzie jej brakuje jakości. Mogą rozpoznać tylko bardziej oczywiste aspekty jakości funkcjonalnej w niej, myląc je z jej głębszą doskonałością. To nie ma znaczenia - będzie dobrze się używać, lub nie, i to jest ważne.
Ale my, jako jej twórcy, potrzebujemy jasnego i skutecznego zrozumienia, co sprawia, że dokumentacja jest dobra. Musimy rozwinąć nasze wyczucie, aby rozpoznać co jest dobre w niej, jak również że jest dobra. I musimy rozwinąć zrozumienie, jak ludzie będą się czuli, gdy będą z niej korzystać.
Tworzenie dzieła o jakości głębokiej zależy od naszej zdolności do tego.
Diátaxis i jakość¶
Obowiązki jakości funkcjonalnej są spełniane poprzez sumienne przestrzeganie wymagań rzemiosła tworzenia dokumentacji. Wymagają one solidnych umiejętności i wiedzy z zakresu domeny technicznej, zdolności do ogarnięcia całego terytorium w jedną, spójną, konsekwentną mapę.
Diátaxis nie może zajmować się jakością funkcjonalną w dokumentacji. Zajmuje się tylko niektórymi aspektami jakości głębokiej, niektórymi bardziej niż innymi - choć jeśli wszystkie aspekty jakości głębokiej są splątane ze sobą, to wpływa na wszystkie z nich.
Ujawnianie uchybień w jakości funkcjonalnej¶
Chociaż Diátaxis nie może zajmować się, lub dać nam, jakości funkcjonalnej, może nadal jej służyć.
Działa bardzo skutecznie ujawniając uchybienia w jakości funkcjonalnej. Często zauważa się, że jednym z efektów stosowania Diátaxis do istniejącej dokumentacji jest to, że problemy w niej nagle stają się widoczne, które wcześniej były ukryte.
Na przykład: podejście Diátaxis zaleca, aby architektura dokumentacji referencyjnej odzwierciedlała architekturę kodu, który dokumentuje. To sprawia, że luki w dokumentacji stają się znacznie bardziej wyraźne.
Lub, przeniesienie wyjaśniającego słownictwa poza tutorial (zgodnie z wymaganiami Diátaxis) często ma efekt podkreślenia sekcji, w której czytelnik został pozostawiony, aby sam coś rozgryzł.
Ale, jeśli chodzi o jakość funkcjonalną, zasady Diátaxis mogą mieć tylko rolę analityczną.
Tworzenie jakości głębokiej¶
W jakości głębokiej natomiast podejście Diátaxis może zrobić więcej.
Na przykład, pomaga dokumentacji dopasować się do potrzeb użytkownika przez opisywanie trybów dokumentacji, które są na nich oparte; jej kategorie istnieją jako odpowiedź na potrzeby.
Musimy zwrócić uwagę na prawidłową organizację tych kategorii, a następnie układ materiału i relacje między nimi, formę i język przyjęty w różnych częściach dokumentacji - jako sposób dopasowania się do potrzeb użytkownika.
Lub, w Diátaxis jesteśmy bezpośrednio zainteresowani płynnością. W płynności - czy kontekst jest dokumentacją, czy czymkolwiek innym - doświadczamy ruchu z jednego etapu lub stanu do drugiego, który wydaje się właściwy, niewymuszony i w zgodzie zarówno z naszymi troskami w danej chwili, jak i sposobem, w jaki nasze umysły i ciała działają ogólnie.
Diátaxis zachowuje płynność, pomagając zapobiegać rodzajowi zakłócenia rytmu, które występuje, gdy coś przeszkadza naszemu celowi i stałemu postępowi w jego kierunku (na przykład, gdy dygresja w wyjaśnienie przerywa przewodnik krok po kroku).
I tak dalej.
Zrozumienie granic¶
Ważne jest, aby zrozumieć, że Diátaxis nigdy nie może być wszystkim, co jest wymagane w dążeniu do jakości głębokiej.
Na przykład, chociaż może pomóc osiągnąć piękno w dokumentacji, przynajmniej w jej ogólnej formie, samo w sobie nie czyni dokumentacji piękną.
Diátaxis oferuje zestaw zasad - nie oferuje formuły. Z pewnością nie może oferować skrótu do sukcesu, omijając umiejętności i wglądy dyscyplin takich jak projektowanie doświadczenia użytkownika lub projektowanie interakcji użytkownika, lub nawet projektowanie wizualne.
Używanie Diátaxis nie gwarantuje jakości głębokiej. Cechy jakości głębokiej są zawsze na nowo negocjowane, reinterpretowane, odkrywane i wymyślane. Ale to, co Diátaxis może zrobić, to postawić pewne warunki dla możliwości jakości głębokiej w dokumentacji.