Пятница, 29.03.2024, 01:56
Мой персональный сайт Добрым людям smart & sober

Главная Регистрация Вход
Приветствую Вас, Гость · RSS
Калькулятор


Меню сайта
Календарь
«  Февраль 2011  »
ПнВтСрЧтПтСбВс
 123456
78910111213
14151617181920
21222324252627
28


Форма входа


Архив записей
Мини-чат


Категории раздела


Наш опрос
В чем заключается ваш смысл жизни
Всего ответов: 154
 
Главная » 2011 » Февраль » 12 » «Обязательно все документируйте» vs «документацию писать бессмысленно»
21:19
«Обязательно все документируйте» vs «документацию писать бессмысленно»
В этой статье хочется обратить внимание на важность двух аспектов разработки ПО.
  • Если Вы делаете продукт, срок разработки которого больше одной недели — обязательно надо писать документацию.
  • Любой документ может начать устаревать непосредственно в процессе своего написания и поэтому документацию писать бессмысленно


Как ни странно документация к некоторым проектам иногда таки пишется. Но не ко всем. И не всегда. Иногда это плохо, иногда нормально. А к некоторым проектам пишется очень много документации. Почему так происходит и как правильно?

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



Для начала приведу несколько примеров продуктов с и без документации из реальной жизни.

#1 iPhone приложение на один раз


Клиенту заказывает проект длинной в полтора месяца на разработку приложения для iPhone. Приложение делается для конкретного автосалона на котором будет представлена новая модель автомобиля. Проект делается одним разработчиком, отдается заказчику и через месяц о нем (о проекте) все забывают.

Документация не нужна никому.

#2 Онлайн аукцион


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

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

#3 Приложение для online рекламы разрабатываемое несколькими командами


Приложение для online рекламы (опущу подробности), два года разрабатывалось командой из десятка индусских программистов. Результат был не то чтобы очень, что-то работало, но не все и не так. Заказчик провел аудит кода, сократил 60% индусов и нанял команду из России допиливать критичный кусок приложения. Также в тусовке принимают участие отдельная группа тестировщиков из Индии и группа админов из Калифорнии (была еще команда делающая Data Warehouse из Вьетнама, но как-то быстро потерялась). Сам заказчик живет в Нью-Йорке. Проекту в такой конфигурации уже скоро год и в целом все неплохо. Хотя и странно.

Без руководства разработчика и руководства администратора вся эта конфигурация не заработала бы никогда. Да, написание документации отнимает определенное время ежедневно, но без этого вести разработку нереально. Что документируется:
  1. Общая схема компонентов и интерфейсов
  2. Детальное описание интерфейсов между компонентами
  3. Описание внешних интерфейсов
  4. Схема БД
  5. Подробное описание всех настроек системы
  6. Руководство как собрать и развернуть систему «с нуля»
  7. Зоны ответственности — кого, где и как искать если что-то случилось


#4 Документация по ГОСТ-у


Лет 10 назад я участвовал в создании комплексной системы энергоучета которая была продана нескольким нефтяным компаниям. Энергоучет автоматически означал поставку примерно 40 килограмм документации на систему. Занимались написанием документов отдельно выделенные 4 человека пол года. Систему поставили, сдали сначала в опытную, а потом и в промышленную эксплуатацию. Что характерно, все что не касалось расключения проводов уже через 6 месяцов где-то на 10-20% не соответствовало действительности, т.к. система постоянно дорабатывалась. Т.е. реально ценность документации стремительно падала.

Несколько выводов



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

Команда в 3 человека пишет приложение для заказчика. Например веб сайт. Тратят они на это 8*3=24 часа в день. Судя по опыту в среднем на поддержание подробного, толкового руководства разработчика в актуальном состоянии надо не менее 2 часов в день регулярно. Что это значит практически.

За месяц набегает примерно 600 часов разработки и 50 часов документирования. Причем документация нужна, по большому счету в двух случаях

  1. Добавляется/меняется член команды
  2. Меняется вендор, т.е. заказчик уходит в другую компанию


Предположим что такая ерунда случается скажем не чаще чем раз в 5 месяцев — получается, что мы тратим 5*50 = 250 часов (фактически больше одного человеко/месяца) на то, чтобы сделать вхождение нового человека в команду/передачу кода другой команде менее болезненной процедурой. При этом надо понимать что наличие простой доки на 3 страницы скажем экономит 30% на вхождение человека в проект, а даже самая наирасподробнейшая документация видимо дает не более 50% экономии времени — сколько документацию не читай, а в код смотреть все равно надо.

Я мог бы еще немного по спекулировать цифрами, но думаю направление мысли понятно и дальше Вы для своего случая досчитаете сами.

Основной тезис здесь следующий — чем более подробна документация тем сложнее (дороже) ее поддерживать в актуальном состоянии и тем меньше она приносит пользы в пересчете на потраченный человеко/час. Например для типичного веб проекта — диаграмма компонентов системы, описание настроек, интерфейсов с другими системами и т.п. очевидно полезны и код их заменяет с трудом. Но например ценность подробной диаграммы классов с именами методов в общем уже значительно ниже т.к. все равно придется в код лезть и глазами смотреть.

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

Антипаттерн

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

  1. Энтузиаста удавалось отпоить чаем, рассказать пару баек из жизни и он уходил умиротворенный
  2. Порыв находил выход и 4-16 часов приносились в жертву написания подробнейшей доки подробно рассказывающей о жизни и трудовой карьере какого-то одного класса и/или модуля приложения. Потом приходила РАБОТА, дока забывалась и через какое-то время теряла актуальность.


Я ни в коем случае не хочу сказать что написание документации всегда бывает бессмысленно. Здесь я говорю о спонтанных, не спланированных приступах документирования которые достаточно часто встречаются у разработчиков всех возрастов.

«Хватит меня путать, как собственно надо?»



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

Любое утверждение вида:
  • Документация не нужна, хорошего кода достаточно
  • Надо документировать все как можно подробнее
  • Надо документировать только вот это и это, все остальное нафиг

в отрыве от контекста, а именно цели проекта, бюджета проекта, состава команды, условий работы и т.д. бессмысленно.

PS: Здесь под документаций в основном понимается руководство разработчика, но в целом выводы применимы к любым сопутствующим текстам.

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

PPPS: Для mission critical систем как правило бюджет достаточно большой и для них в 99% применимо утверждение «документировать все». Но это тем не менее не отрицает думание головой.
Просмотров: 633 | Добавил: Breger | Рейтинг: 0.0/0
Всего комментариев: 0
Добавлять комментарии могут только зарегистрированные пользователи.
[ Регистрация | Вход ]
Copyright MyCorp © 2024