Diátaxis: системний підхід до написання технічної документації

Diátaxis — це системний підхід до написання технічної документації. Його автор, Даніеле Прочіда, описує його як спосіб думати про документацію та працювати з нею: він визначає підходи до змісту, архітектури й форми, що випливають із вивчення потреб користувачів документації.

Чотири види документації

Основна ідея полягає в тому, що існують чотири принципово різні види документації, які відповідають чотирьом різним потребам: туторіали, інструкції (how-to guides), довідники (reference) та пояснення (explanation). Кожен має власне призначення і вимагає іншого стилю написання. Туторіал — це урок, який веде учня за руку через досвід навчання; він завжди практичний, як-от урок водіння. Інструкція допомагає вже досвідченому користувачеві досягти реальної мети чи розв'язати проблему; вона про роботу, а не про навчання. Довідник містить технічні факти, потрібні для коректних дій: точні, повні й вільні від інтерпретацій, як морська карта. Пояснення ж дає контекст і передісторію, пов'язує речі між собою та відповідає на питання «чому».

Карта й компас

Diátaxis розташовує ці чотири види на концептуальній карті та додає компас, який допомагає визначити, де має бути конкретний матеріал. Туторіали й інструкції стосуються того, що користувач робить (дія), а довідники й пояснення — того, що користувач знає (пізнання). Туторіали й пояснення служать набуттю навичок, тобто навчанню; інструкції й довідники — застосуванню навичок, тобто роботі. За словами авторів проєкту, саме перетинання чи розмивання цих меж лежить в основі величезної кількості проблем у документації.

Перевірено на практиці

Підхід заявлений як легкий, зрозумілий і такий, що не нав'язує технічних обмежень; його принципи успішно застосовано в сотнях документаційних проєктів. Грег Фріло з Vonage каже, що Diátaxis дозволив створити якісну внутрішню документацію; Меган Салліван розповідає, що проєкт Gatsby спирався на цю структуру, реорганізовуючи документацію з відкритим кодом, а чотири квадранти допомогли розставити пріоритети між типами документів; Адам Шварц згадує, що під час переробки документації для розробників Cloudflare Diátaxis став «провідною зіркою нашої інформаційної архітектури».

Як почати

Порада самого сайту: почніть із застосування — до чогось, хай навіть зовсім малого. Рекомендований робочий цикл: подивіться на документацію, яка зараз перед вами, запитайте, чи можна її якось покращити, виберіть одну річ, яку можете зробити просто зараз, і зробіть її; потім повторіть. Вірити в теорію не обов'язково: автор називає підхід цілком прагматичним, чия цінність — у допомозі людям створювати кращу документацію.