Миф о документации

[mazzy]

Миф о документации
http://gaperton.livejournal.com/60632.html

[macklakov]

хорошая статья.
Есть, правда, в консалтинге еще один вид документов. Под названием "проектная документация". Это такой огромный ворох шуршашей оберточной бумаги, в который заворачивают механизм, дабы клиент не вымазался в мазуте и не зашиб колено об выступающие детали. Бумагу принято украшать цветными диаграммами, абстрактными скрин-шотами и загадочными таблицами. Инжинер-моторист должен, презрев эстетику, бумагу сорвать, скомкать и отбросить. И после этого совершить тщательный осмотр изделия, чтобы понять чтоже собственно ему предстоит обслуживать.

[gl00mie]

Статья действительно интересная, чувствуется, что "выстраданная" Но утверждения на счет противопоставления договора и справочника, мне кажется, - не бесспорны. Выделение полужирным далее - моё.

Цитата:

Итак, мы выяснили, что:

• по решаемым проблемам «документы» можно условно разделить на «договор», «справочник», и «учебник», и хоть это и не полный список, но вполне достаточный для наших целей.
• Документ типа «договор» пишут и читают добровольно все, или многие, ибо иначе придет <censored>.
• «Договор» нет нужны «поддерживать в актуальном состоянии», ибо это лежит за рамками проблемы, решаемой «договором».
• Основная фишка «справочника» в том, что ему точно можно доверять, и он всегда актуален.
• «Справочники» очень дороги в создании и содержании, и нужна действительно веская причина, чтобы его создавать. Меняется справочник редко.

«Справочником» в нашем случае является исходный текст программы, с комментариями в тексте, и с комментариями к коммитам в системе контроля версий. Для тех, кто не умеет читать код – для практически всех современных языков есть автоматические генераторы «справочников» из кода, вроде JavaDoc, волшебным образом решающие проблему актуальности.
Тексты типа «договор», которые в нашем случае отражают требования, иногда результат проектирования, и пр. – не надо пытаться превращать в документы типа «справочник», и поддерживать актуальными. Они решают совсем другую проблему. Эта идиотская затея провалится просто потому, что это <censored> никому не нужно.

Вспомнилась в связи с этим чудесная книга Балдеющие от адреналина и зомбированные шаблонами Тома Демарко, Тимоти Листера & Co, в частности, шаблон №43 "Эти чертовы интерфейсы"

Цитата:

Члены проектной команды неотступно концентрируются на интерфейсах – как автоматизированных, так и человеческих.
Чтобы спроектировать систему, нам следует понять, какие интерфейсы должны быть между этой системой и ее окружением. Нам нужно знать, какие данные поступают на вход и что система производит на выходе. Пока у нас нет такого перечня входов и выходов, мы остаемся на стадии предварительного анализа: мы не ограничили задачу. Получив полный набор интерфейсных характеристик, мы можем заняться определением функциональности системы.
Что происходит в проектировании после того, как достигнуто согласие по поводу функциональности? Мы разбиваем большую и сложную систему на подсистемы, а подсистемы делим на компоненты. И снова, для того чтобы ограничить эти подсистемы и компоненты, необходимо в каждом случае определить все уникальные входы и выходы.
Как мы фрагментируем деятельность по реализации? По подсистемам и/или компонентам. Команда может взяться за работу над подсистемой, при этом отдельные люди будут создавать и тестировать
компоненты. Границы подсистемы и компонента задают фронт работ, определяя конкретную область ответственности каждого разработчика. Интерфейсы играют роль контрактов между компонентами; один компонент говорит другому: «Ты передаешь мне именно такие данные и только при таких условиях, а я создам именно такой результат, который будет храниться точно в указанном месте».
Знакомые с этим паттерном команды начинают штурмовать интерфейсы как можно раньше. Они создают фрагменты кода для работы интерфейсов еще до того, как начнут писать код компонентов. Они рано начинают интеграцию кода отдельных разработчиков и часто проводят тестирование.
Мы как-то имели дело с проектом, который вели три рабочие группы – одна в Канаде, другая в США, а третья в Израиле. Руководитель держал в интранет-сети проекта документ с названием «Библия интерфейсов». Этот справочный документ служил единственным источником информации по всем интерфейсам системы, и только включенные в него особенности интерфейсов имели право на существование. Он клялся на этой библии, и поэтому ему не приходилось проклинать интерфейсы.

Тут приводится пример того, как один документ может играть роли договора (контракта) и справочника в классификации автора статьи, при этом он

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

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

[komar]

Мне приходилось встречать такое определение договора - это "документ, который достаётся тогда, когда проект заходит в тупик"

[MARKZeon]

Договор в основном пишут юристы для юристов для борьбы со странными заказчиками и поставщиками, ведь им потом расхлебывать

[macklakov]

Цитата:

Сообщение от MARKZeon

Договор в основном пишут юристы для юристов для борьбы со странными заказчиками и поставщиками, ведь им потом расхлебывать

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