diataxis – типы документации
Диатаксис (греч. Διάταξις — «устав») — в X—XII вв. в Византии так называли текст, регламентировавший обрядовую сторону совершения богослужения. Появление их было вызвано тем, что в рукописях богослужебных книг содержались лишь молитвословия - тексты, произносимые священником и диаконом, но практическое совершение богослужебных действий эти тексты не описывали. Самые известные из диатаксисов, в основе своей регламентирующие и современную практику совершения богослужения — диатаксисы Божественной литургии и всенощного бдения, автором которых был константинопольский патриарх Филофей Коккин (1353—1354 гг.).
– https://ru.wikipedia.org/wiki/%D0%94%D0%B8%D0%B0%D1%82%D0%B0%D0%BA%D1%81%D0%B8%D1%81
А в наших техрайтерских краях Diátaxis — подход к разработке документации, когда каждый раздел или документ относится к одному из типов жанров:
| Описательные | Директивные | |
|---|---|---|
| Обучающие | Концепции | Туториалы |
| Для работы | Справочники | Инструкции, руководства, howto |
- Концепции (concepts, explanations) — описывают понятия, концепции, объекты, составляющие систему.
- Справочники (references) — полный список однородных компонентов продукта. Это могут быть ключи командной строки, элементы синтаксиса, настройки, параметры, запросы к API, коды ошибок и т. п.
- Туториалы (tutorials) — обучающие задачи с пошаговым решением. Проходя туториал, пользователь на конкретных примерах разбирается, как работает система. Решение поставленной задачи является не самоцелью туториала, а средством обучения пользователя.
- Инструкции, руководства (howto guides) — пошаговые инструкции по работе с продуктом, призваны помочь решить конкретную рабочую задачу.
Обычно никто не читает документацию от корки до корки. На разных этапах знакомства с продуктом пользователь решает с помощью документации разные задачи:
- Познакомиться с продуктом, понять, подходит ли ему продукт, в чём его особенности. Концепции.
- Поставить и настроить продукт, потестировать, чтобы научиться с ним работать. Туториал.
- Найти инструкцию по решению задачи, возникшей при работе с продуктом. Инструкции.
- Понять, можно ли сделать нужное при помощи вот этого инструмента, и если да, то как. Справочник, оттуда, возможно, инструкция.
https://habr.com/ru/companies/documentat/articles/766926/
- https://diataxis.fr/ - офсайт.
- https://github.com/evildmp/diataxis-documentation-framework – гитхаб сайта.
- https://idratherbewriting.com/blog/what-is-diataxis-documentation-framework – вроде, норм статья про.