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 – вроде, норм статья про.
От жанра и ЦА зависит количество дополнительной информации в тексте.
Чем больше в документе обучения, тем больше нужны «самопроверки», описание результата шага.
Если брать «приблизительно инструкцию», то можно противопоставить чеклист и туториал для предельного новичка, понимая, что может быть много промежуточных вариантов.
В случае чеклиста предполагается, что адресат документа всё сам знает, умеет, 100500 раз делал, в принципе, и без чеклиста мог бы обойтись, но с чеклистом результат надёжнее. :) Поэтому достаточно перечисления шагов/действий, названных максимально кратко.
В случае туториала, конечно, всё равно человек что-то уже знает и умеет. Как минимум, уже умеет читать ;) Но шаги описываем подробно и детально, и вставляем много самопроверок. Вот, я сделала это действие, я всё правильно сделала? Как я могу это узнать? Вообще, всё идёт как надо? В результате действия должно было получиться вот это. Да, оно получилось! Ура, всё в порядке, можно продолжать. Нет? Что пошло не так? Именно ради возможности проверить, всё ли ожидаемо, приводятся «откроется такое окно», «результат выполнения команды выглядит вот так», cкриншоты, цитаты — всё, с чем можно свериться.