A technikai dokumentációk jelentős része gyenge minőségű, nagyobb mértékben azért, mert minimális időt és energiát fordítanak a megírásukra; nem a használhatóság, hanem egy kötelező gyakorlat teljesítése a cél. Csakhogy ha azért készül dokumentáció, hogy használják, akkor sem mindig sikerül elfogadható minőségűre, mégpedig gyakran azért nem, mert szem elől tévesztik a célközönséget, illetve az igényeket. Ebben segít a Diátaxis keretrendszer, amely négy típusát különbözteti meg a technikai dokumentációnak:

  • Oktatóanyag (tutorial): végigvezeti az olvasót egy olyan lépéssorozaton, amellyel megold valamiféle problémát. Tanulásorientált, alapkompetenciák elsajátításához való.
  • Útmutató (how-to guide): irányítja az olvasót, milyen lépésekkel oldhat meg egy konkrét gyakorlati problémát. Eredményorientált, egy már kompetens olvasót segít.
  • Referencia (reference): felsorolások, listák, táblázatok. Általában megjegyezhetetlen, segédeszköz munkához.
  • Magyarázat (explanation): áttekintések, elemzések, tanulmányok. Elméleti tudást ad, tanuláshoz kell.

Zachman + Diátaxis

A Diátaxis összeegyeztethető a Zachman-keretrendszerrel. Az előbbi arra irányul, hogyan írjunk dokumentációt, az utóbbi pedig arra, mit dokumentáljunk és kinek a szemszögéből. Az előbbi olvasóorientált megközelítés, az utóbbi teljeskörű vállalati lefedettségre törekvő. Például:

  • Oktatóanyag (tutorial): Owner/Designer – Miért/Mit (pl.: Első lépések DWH-felhasználóként)
  • Útmutató (how-to guide): Builder – Hogyan/Hol (pl.: Hogyan készítsünk új ETL csatornát)
  • Referencia (reference): Subcontractor – Mit/Ki (pl.: Az értékesítési adatkör üzleti fogalomtára)
  • Magyarázat (explanation): Planner/Owner – Miért (pl.: DWH tervezési koncepció)

Gyakorlati lépések a két keretrendszer integrációjához:

  • Kezdjünk a Zachmannal, azonosítsuk a témaköröket a perspektívákon át.
  • Alkalmazzuk a Diátaxist minden témakörre:
    • Tegyük fel a kérdést magunknak: oktatóanyag, útmutató, referencia vagy magyarázat a megfelelő műfaj?
  • Hozzuk létre az egyes dokumentumokat:
    • Használjuk a Zachmant a téma lefedettségének megítélésére.
    • Használjuk a Diátaxist a dokumentum felépítéséhez: kis lépésekben, iteratívan.