Принцип DRY при написании документации

В разработке принцип "Не повторяйся" (Don't Repeat Yourself, DRY) является одним из ключевых для эффективности и качества итогового продукта. Его же можно использовать и в подготовке документации.

Основной смысл: каждая часть знания должна иметь единственное, непротиворечивое и авторитетное представление в рамках системы.

Согласитесь, очень часто мы забываем и о системе (концентрируясь лишь на единственной его части), и о непротиворечивости (правим доки в одном месте и забываем о других).

Мои советы по использованию этого принципа:

1. Внедрение шаблонов
Большинство документов подлежит стандартизации. Используйте шаблоны не только для сокращения бесполезного труда, но и для систематизации. Хорошо структурированный документ всегда понятнее и чаще всего оставляет меньше простора для явных ошибок.

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

3. Контроль версий
Системы контроля версий актуальны не только для кода и разработки, но и для поддержания информации в актуальном виде — мы всегда можем "откатиться" к старой версии или понять кто, что и когда изменял (и пойти к этому человеку с вопросами). Сейчас контроль версий есть в большинстве систем для работы с информацией (Notion, Confluence, Google Docs, etc).

Ключ к хорошей документации — в постоянном стремлении к упрощению и оптимизации процесса её написания. В конце концов, некачественная документация столь же бесполезна, как и её полное отсутствие.

#документация