Comments 9
Звучит интересно, сам пришёл к чему-то похожему, но очень не хватает какого-то обоснования для такой системы. Особенно самому строгому правилу "они не должны смешиваться". Почему?
У меня есть свои предположения, но хотелось бы услышать мнение автора этой теории.
Автор развил изложенные на сайте Divio идеи: https://diataxis.fr/.
Что-то я не вижу принципиальной разницы между хауту и руководством. Фактически руководство - это один большой структурированный хауту.
Ну а референс в документации и не нужен, и даже вреден - ему место в IDE, рядом с кодом.
Скорее, руководство (manual/guide?) состоит из множества howto, сгруппированных по темам. Иногда в нем есть и reference, и explanation. То есть руководство и не должно входить в классификацию, это формат издания.
Техническая документация не только для кода. Например, есть система защиты от атак. Есть howto, как настроить автоматическую защиту от атак определенного вида, в ходе которого настраиваются конкретные алерты. Есть reference со всеми доступными алертами и их видами (в подсказках к UI не развернешься). Есть explanation логики, по которой организованы алерты.
Нет существенной разницы между учебником и руководством:
Как и в учебниках, подробные пояснения здесь неуместны.
И в описании учебника довольно абсурдное
но любое обучение идёт от частного и конкретного к общему и абстрактному.
Если взять любой нормальный учебник по физике или математике, то там всё как раз наоборот: сначала вводится и объясняется понятийный аппарат, затем вводятся концепции, теоремы, леммы, рассматриваются общие принципиальные закономерности (фундаментальные уравнения теории, например), а затем, в конце главы/раздела, если это уместно -- здесь же упражнения для закрепления материала. Это называется систематическим обучением. А то, что описано в статье -- это руководство по решению задач, а не учебник. И принцип построения "объяснения" совершенно не решает проблему понимания, там вообще о чём-то другом написано.
Это не типы - это виды (по форме) одного типа (по содержанию) - руководства пользователя. Остальные типы давно описаны в iso и неоднократно повторены в ГОСТ и фреймворках (TOGAF и др.). Хотя чего можно ожидать от очередной теории всего?
Правильнее ссылаться на https://diataxis.fr/
На сайте Divio изложены эти же идеи, этим же словами и этим же автором, он в то время работал на Divio. Но Diataxis это официальное название этого подхода, чтобы вам не приходилось выдумывать свое, типа "Великой, единой...". На теорию всего он, кстати, не претендует. Это вообще не теория. Это практический подход к созданию пользовательской (!) документации. И то, в какой мере вам удобно этот подход применять, решать только вам. Это зависит и от системы и от ЦА и других факторов. И автор об этом честно пишет.
На Хабре, кстати, есть другая статья про этот же подход: https://habr.com/ru/companies/documentat/articles/766926/
Впрочем, как сторонник подхода, я рад, что про него появляются еще статьи и больше людей про него узнает :)
4 стихии программной документации: The Grand Unified Theory of Documentation