TGViewer
Записки системного архитектора Записки системного архитектора @sysarchthoughts · 269 subscribers
Post #142 350
Записки системного архитектора А давайте поговорим про документацию. Сколько раз вы слышали, что обязательно нужно разработать полную документацию по продукту, а без этого ничего не получится? Я такое слышал очень часто. И постепенно пришел к выводу, что слова "полная документация" нужно…
Еще несколько слов про требования к документации, в ответ на комментарий. Действительно, требования к документации не "висят в воздухе", они привязаны к контексту, к цели проекта, продукту, зависят от текущей стадии ЖЦ, объемов инвестиций/финансирования и т.п. Я хотел акцентировать внимание на том, что часто встречающееся требование "полноты" документации бессмысленно и даже вредно.

Вот к примеру, масштабная цель - выпустить на рынок B2E продукт, который будет использоваться в больших организациях и внедряться усилиями интеграторов-партнеров. Какие требования к документации предъявляются? Внедренцы хором говорят - нам нужна полная документация по возможностям продукта. Что это, блин, такое? Продавцы, вы не поверите, говорят те же самые слова. Но имеют в виду совсем другое. Правда, ни одни, ни другие не могут объяснить что именно им нужно.

И вот, чтобы процесс создания документации был как-то связан с заявленной целью, мы вместо неприличных неявных требований, формулируем явные требования к документации. Сначала высокоуровневые, аналог НФТ.
Документация должна быть:
1. Полезна для .... — тут вставляем для кого и чего пишем документацию
2. Своевременна — первый полезный вариант должен быть не позже чем ...
3. Посильна по ресурсам — ограничения на объем и ресурсы, которые можем потратить

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

А уже дальше, под каждым пунктом будут прорастать более детальные требования и ограничения - по структуре, формату и т.п.
И тут очень важна прослеживаемая трассировка Цель — характеристика — конкретное требование
Например,
Делаем продукт для B2E
документация должна быть полезна для инженеров внедрения
Нужен документ "Руководство по развертыванию и настройке"
Структура документа: .....
Доступен онлайн
Поддерживает поиск по ключевым словам


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

P.S. А если самим требования к документации формулировать лениво - используйте ГОСТы и не жужжите :) Некоторые заказчики так и делают.
Telegram Vadim Zhivotovsky in Записки системного архитектора Chat Объём документирования должен соответствовать требованиям к документированию. Документирование - это часть проекта, т.е. часть его цели. Требования к документации должны быть заложены в самом начале проекта ровно как и остальные требования, соот-но, оценены…
  • 👍 2
More from @sysarchthoughts
  1. Aug 4, 2026Мне жена как-то сказала, что только в зрелом возрасте осознала трагедию сказки о рыбаке и…
  2. Jul 2, 2026Я не давлю. Я пытаюсь опереться.
  3. Apr 2, 2026Пригласили меня тут в жюри школьного проектного конкурса, и вот что хочу сказать: мало кто…
  4. Mar 22, 2026Как технические границы делают все бизнес-критичным? Ключевой вопрос, которому посвящена э…
  5. Mar 22, 2026Неуловимо напоминает "основной закон органической химии". Если смешать бочку мёда и бочку…
  6. Mar 10, 2026(продолжение рассуждений про больницу) Что мне тут понравилось, что беру на заметку. 1. Че…
Threads Profile ViewerView any public Threads profile without an account.Open ThreadLook →Writing with AI? Make it sound human.Metric37 rewrites AI drafts so they read naturally. Free AI detector, 1,500 words free.Try Metric37 →