Функции документов

Функция объясняет, как читать и применять документ. Она не определяет предмет документа, его место в главном меню, каноничность или видимость. Например, философский текст может принадлежать Governance, а standard — U.L.I. или Knowledge System.

Смысл и ориентация

index 🧭

Является входом в систему или домен: определяет его предмет, границы, состав и следующие маршруты. Index не дублирует все дочерние документы.

philosophy 🌿

Выражает основания, образ желаемого будущего и культурный смысл. Может быть сильным и манифестным, но не создаёт обязательной процедуры автоматически.

principle 🧭

Фиксирует устойчивую установку, которой руководствуются в разных ситуациях. Принцип направляет judgment, но обычно требует policy или standard для однозначного исполнения.

guide 🗺️

Помогает выбрать маршрут: что читать, куда перейти, какую систему или роль затрагивает вопрос. Не обязан содержать полную теорию или пошаговую операцию.

explanation 🔍

Объясняет, почему система устроена определённым образом, какие части связаны и где проходят границы. Даёт понимание, но сам по себе не всегда нормативен.

Нормативные функции

standard 📏

Определяет обязательную форму объекта, артефакта или результата: поля, инварианты, допустимые значения и критерии соответствия.

policy 🛡️

Определяет разрешения, запреты, ответственность, исключения, контроль и порядок изменения. Policy отвечает, что должно происходить при определённых условиях.

Нормативная сила зависит не только от функции, но и от governance.canonicality, owner, approver и status.

Справка и обучение

reference 📋

Даёт структурированный ответ о понятиях, параметрах, состояниях или интерфейсах. Reference может быть публичным или закрытым — видимость задаётся отдельно.

tutorial 📚

Обучает через последовательный путь и помогает впервые освоить целостный процесс или инструмент.

Tutorial определяет функцию документа, а не обязательное место хранения. В DETai сейчас существуют два разных масштаба tutorial.

Экосистемный onboarding tutorial

Экосистемный onboarding tutorial ведёт нового участника, который вступает в команду DETai, через общий маршрут знакомства, подключения к рабочей среде и первым действиям. Сейчас такие материалы живут в публичном репозитории DETai-org/onboarding, где они могут быть связаны с Issues, чекпоинтами и другими onboarding-механиками.

Такой tutorial принадлежит не отдельному продукту, а общему маршруту входа в экосистему.

Project-specific tutorial

Project-specific tutorial обучает работе с конкретным проектом, инструментом или интерфейсом. Он может храниться в owning repository самого проекта, особенно если:

• шаги зависят от текущей реализации;
• текст должен меняться в том же PR, что и функция;
• tutorial используется как встроенная помощь интерфейса;
• проекту нужен один source of truth для Git-документа и runtime-проекции.

В таком случае tutorial остаётся tutorial по функции, хотя физически находится не в Onboarding. Если он одновременно показывается внутри продукта, интерфейс должен проецировать этот source of truth, а не поддерживать независимую копию текста.

how-to ⚙️

Показывает, как выполнить конкретную задачу для читателя, который уже понимает контекст. Как и tutorial, how-to может жить в Onboarding для общего маршрута либо рядом с проектом, если относится к конкретному инструменту и должен изменяться вместе с его реализацией.

runbook 🚨

Задаёт проверенную последовательность действий для повторяемой операционной ситуации, особенно инцидента, выпуска или восстановления.

Управление изменениями и работой

decision-record ⚖️

Фиксирует контекст, принятое решение, альтернативы, основания, последствия и статус. Не переписывается как будто прежнего решения не существовало; изменение создаёт новую запись или явную связь supersedes.

register 🗂️

Удерживает набор однотипных управляемых объектов: claims, risks, decisions, owners, policies или products. Register требует правил идентичности и обновления.

brief 🎯

Передаёт исполнителю ограниченную задачу, контекст, требования, границы и критерии готовности. Brief не становится каноном только потому, что по нему выполнена работа.

log-summary 🧾

Сохраняет датированный итог действий или состояния. Он является свидетельством истории, но не инструкцией и не текущей policy. Переносимый формат, provenance и Folder-local ClickUp route определяет contract type: log-summary.

note ✍️

Содержит наблюдения, вопросы или сырые предложения без нормативной силы. Если note используется для решения, её тезис должен быть продвинут в подходящий канонический объект.

Краткая матрица

Функция	Главный вопрос	Типичное применение
index	Что это за система и куда идти дальше?	вход в раздел
philosophy	Во имя чего?	культура и мотивация
principle	Чем руководствоваться?	устойчивый judgment
guide	Куда идти?	навигация
explanation	Почему так устроено?	понимание системы
standard	Как выглядит правильный объект?	форма и критерии
policy	Что разрешено, требуется или запрещено?	управление поведением
reference	Каковы факты и параметры?	справка
tutorial	Как впервые освоить целое?	обучение
how-to	Как выполнить одну задачу?	практическая инструкция
runbook	Что делать в повторяемой ситуации?	операция или инцидент
decision-record	Что и почему решили?	история решений
register	Какие управляемые объекты существуют?	контроль состояния
brief	Что должен сделать исполнитель?	передача работы
log-summary	Что произошло?	история исполнения
note	Что замечено или предполагается?	сырой контекст

Правило выбора

Документ получает функцию по своему главному пользовательскому действию. Если текст одновременно пытается вдохновлять, нормировать, обучать и вести реестр, его следует разделить или явно назвать основную функцию и вынести остальные артефакты в связанные документы.

Место хранения выбирается отдельно: по масштабу документа, owning-системе и тому, должен ли текст версионироваться вместе с конкретной реализацией.