done. Немного поправил и структурировал, в остальном без изменений.

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

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

Я бы прямо с каждым сотрудником несколько раз прошёл этот путь, чтобы убедиться, что мы одинаково понимаем цели.

— сделать шаблоны разных документов: функциональная и техническая спецификация, описание архитектуры, фоллоуап после обсуждения и т.п.

шаблоны ещё и ускоряют сильно написание. Не надо начинать с чистого листа — это трудно.

И помогают не забыть о важных аспектах.

Про шаблоны пара постов в бэклоге лежит у меня )))

И как только появляется документ под новую цель - люди фигачат бездумно, даже не задаваясь вопросом, что что-то не так

Может, ввести шаг «подумай, про что документ»?

А как бы ты это понял?

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

Приветствую всех, кто зашёл в чат. Если что, тут ещё канал есть: @docops.

Игорь, а есть уже хорошие примеры доков? Можно из них извлечь критерии качества?

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

Код не заработает сразу, если в нем синтаксические/структурные ошибки.есть немедленная обратная связь для джуна.
В случае доки "не заработает"=не зайдет пользователям. Фидбэк через недели. Слишком поздно.

Эту мысль я давно думаю, но пока выборка маловата - сложно экстраполировать.

У вас пользователи — ваши сотрудники? Можно ли дать доку почитать другому джуну или просто кому-то, кто мало знаком с темой?

Проблема в точности изложения материала, или в форме представления (структуре)?
Имхо, сейчас идёт путаница теплого с мягким.

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