Вчера и сегодня несколько статей и мемов в Сетке по поводу обеспечения проекта документацией. В том числе, помимо юмора, там был ряд идей, характерных для того, что я наблюдал на проектах, о них и захотелось поговорить. Под документацией я имею в виду Бизнес- и Технические задания, паспорт качества и т.д. - т.е. прикладную документацию, гайды...То, с чем специалисты "в поле" руками работают.

О каких мифах я говорю:

❌ Заказчик/Поставщик(например, аналитик для ТЗ, разработчик для паспорта качества) знает, что должно быть в документе.

❌ Документация закроет большинство вопросов

❌ Поставили документ с поставкой продукта и можно больше к нему не возвращаться.

Я ни разу не видел, что бы это работало на практике. И вот почему:

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

👉При создании какого-то кастомного шаблона, заказчику/поставщику крайне трудно самому придумать шаблон. Почему? см.выше - ему и так всё очевидно. Для него это задача превратится в "опиши то, не знаю, что".

Так что, спасение утопающих - дело рук утопающих. Если есть потребность в информации, её может обеспечить через запрос только тот, кому она нужна. Окружающие - не телепаты 🤯

👉Документация не закроет всех вопросов. Опять же, потому что все вопросы не были и не могут быть озвучены в момент написания документации. Очень хороший документ, принятый с ревью, закроект ~85-95% вопросов по задаче. И нормой является по остальным 5% ходить к людям. А если Вы попытаетесь добить этот % до 100, Вы превратите работу в бюрократический ад без заметного эффекта - потому что правка любого документа по конкретному кейсу (часто, на коленке) совершенно не будет означать изменения "в целом по больнице". А чаще будет делать хуже, т.к. будет риск рассинхронизации,. И при этом, будет выматывать людей :)

👉С ростом проекта накладные расходы на ведение документации растут в геометрической прогрессии. Постепенно становится невозможно уложить требования в 1 ТЗ, появляются уровни иерархии, версии ТЗ, версии ТЗ на головные- и подмодули. И при каждой доработке требуется следить, что бы всё это было корректно обновлено. В этот момент, из пункта выше % скатывается ближе к ~85 и это - нормально, даже хорошо.

👉 И мы подходим к вишенке - документация на любой объект системы устаревает в момент её публикации. Это означает, что если я, работая на проекте, вижу документ, обновлённый 1-2 года назад, я апприори не буду ему до конца доверять. Даже если перепроверю, что и код обновлялся тогда же. Потому что достаточно сложный проект имеет кучу связей и не известно, актуальны ли все связи этого модуля или про него просто забыли.

Что это даёт на выходе: ✅Документация нужна. На сколь нибудь сложном проекте - жизненно необходима. ✅ Она закроет основную массу вопросов ❌Она не будет жить вечно. на примерах выше, чем большего качества Вы стремитесь достичь в документации, тем больших трудозатрат потребует написание, а главное - поддержка актуальности документации ❌ Документация не может заменить общения с людьми. Её задача - не в этом. Задача - что бы не задалбывать с тривиальными повторяющимися вопросами. ✅ Хочешь достаточно информации в документ - иди и попроси.Никто вокруг тебя, каким бы специалистом он был - не угадает, что тебе нужно и как именно должен выглядеть документ твоей мечты.😍