Mapa¶

Problem struktury¶

Gdy dokumentacja nie osiąga dobrej struktury, rzadko jest to tylko problem struktury (choć to wystarczająco złe, że utrudnia używanie i utrzymanie). Wady architektoniczne zarażają i osłabiają treść.

W braku jasnej, uogólnionej architektury dokumentacji, twórcy dokumentacji często próbują strukturyzować swoją pracę wokół cech produktu.

To rzadko jest skuteczne, nawet w pojedynczym przypadku. W portfolio przypadków dokumentacji wyniki są dziką niespójnością. Znacznie lepsze jest przyjęcie schematu, który próbuje odpowiedzieć na pytanie: jak organizować dokumentację w ogóle?

W rzeczywistości każda uporządkowana próba zorganizowania dokumentacji w wyraźne kategorie treści pomoże ją poprawić (dla autorów, jak i użytkowników), dostarczając list typów treści.

Mimo to autorzy często znajdują się w sytuacji, gdy muszą pisać konkretną treść dokumentacji, która nie pasuje dobrze w kategorie proponowane przez schemat, lub zmagają się z przepisywaniem istniejącego materiału. Często jest poczucie arbitralności w strukturze, z którą pracują - dlaczego ta konkretna lista typów treści, a nie inna? A jeśli zaproponowana jest inna konkurencyjna lista, którą przyjąć?

Oczekiwania i wskazówki¶

Jasną zaletą organizowania materiału w ten sposób jest to, że dostarcza on zarówno oczekiwań (dla czytelnika), jak i wskazówek (dla autora). Jasne jest, jaki jest cel konkretnego kawałka treści, określa, jak powinien być napisany i pokazuje, gdzie powinien być umieszczony.

Każdy kawałek treści jest rodzaju, który nie tylko ma jedno konkretne zadanie do wykonania, ale to zadanie jest również wyraźnie odróżnione i skontrastowane z innymi funkcjami dokumentacji.

Zamglenie¶

Większość systemów dokumentacji i autorów rozpoznaje przynajmniej niektóre z tych rozróżnień i próbuje ich przestrzegać w praktyce.

Jednak istnieje pewne naturalne powinowactwo między każdą z różnych form dokumentacji a jej sąsiadami na mapie, i naturalna tendencja do zamazywania rozróżnień (co można zobaczyć wielokrotnie w przykładach dokumentacji).

Gdy te rozróżnienia są pozwolone na zamglenie, różne rodzaje dokumentacji przenikają się nawzajem. Styl pisania i treść trafiają w niewłaściwe miejsca. Powoduje to również problemy strukturalne, które jeszcze bardziej utrudniają utrzymanie dyscypliny odpowiedniego pisania.

W najgorszym przypadku dochodzi do całkowitego lub częściowego załamania tutoriali i przewodników krok po kroku w siebie nawzajem, co uniemożliwia spełnienie potrzeb obsługiwanych przez żaden z nich.

Podróż wokół mapy¶

Diátaxis ma pomóc dokumentacji lepiej służyć użytkownikom w ich cyklu interakcji z produktem.

Ta fraza nie powinna być rozumiana zbyt dosłownie. Nie jest tak, że użytkownik musi napotykać różne rodzaje dokumentacji w kolejności tutoriale > przewodniki krok po kroku > techniczne referencje > wyjaśnienia. W praktyce rzeczywisty użytkownik może wejść do dokumentacji w dowolnym miejscu w poszukiwaniu wskazówek na jakiś konkretny temat, a to, co chce przeczytać, będzie się zmieniać z chwili na chwilę podczas korzystania z Twojej dokumentacji.

Jednak idea cyklu potrzeb dokumentacji, który przechodzi przez różne fazy, jest słuszna i odpowiada sposobowi, w jaki ludzie faktycznie stają się ekspertami w rzemiośle. Jest sens i znaczenie w tym uporządkowaniu.

• faza zorientowana na naukę: Zaczynamy od nauki, a nauka umiejętności oznacza od razu zabranie się za jej wykonywanie - pod kierunkiem nauczyciela, jeśli mamy szczęście.

• faza zorientowana na cel: Następnie chcemy wykorzystać tę umiejętność.

• faza zorientowana na informację: Jak tylko nasza praca wymaga wiedzy, której nie mamy jeszcze w głowie, wymaga to od nas skonsultowania się z technicznymi referencjami.

• faza zorientowana na wyjaśnienie: Na koniec, z dala od pracy, zastanawiamy się nad naszą praktyką i wiedzą, aby zrozumieć całość.

A potem wracamy do początku, być może po to, aby uchwycić coś nowego, lub zgłębić bardziej.