|
|
 |
|
 |
Главная » 2011 » Февраль » 12 » «Обязательно все документируйте» vs «документацию писать бессмысленно»
21:19 «Обязательно все документируйте» vs «документацию писать бессмысленно» |
В этой статье хочется обратить внимание на важность двух аспектов разработки ПО.
- Если Вы делаете продукт, срок разработки которого больше одной недели — обязательно надо писать документацию.
- Любой документ может начать устаревать непосредственно в процессе своего написания и поэтому документацию писать бессмысленно
Как ни странно документация к некоторым проектам иногда таки пишется.
Но не ко всем. И не всегда. Иногда это плохо, иногда нормально. А к
некоторым проектам пишется очень много документации. Почему так
происходит и как правильно?
UPD: В статье не рассматриваются такие документы как список требований
или например договор с заказчиком о том сколько и когда будет
заплачено. Подразумевается что полезность ТАКИХ документов если кому-то
и не очевидна, то в любом случае это вопрос не для этой статьи. В
основном тут речь о руководстве разработчика и родственных ему
документах.
Для начала приведу несколько примеров продуктов с и без документации из реальной жизни.
#1 iPhone приложение на один раз
Клиенту заказывает проект длинной в полтора месяца на разработку
приложения для iPhone. Приложение делается для конкретного автосалона
на котором будет представлена новая модель автомобиля. Проект делается
одним разработчиком, отдается заказчику и через месяц о нем (о проекте)
все забывают.
Документация не нужна никому.
#2 Онлайн аукцион
В течении полугода команда разрабатывает для заказчика онлайн аукцион.
Сайт запускается и работает. После запуска команда немного уменьшается
и начинает дополнять сайт новой функциональностью, что продолжается и
по сей день. Руководство пользователя заказчик пишет сам т.к.
пользователи англоязычные, а разработчики нет и заказчику проще и
дешевле написать документацию пользователя самому.
Руководство разработчика заказчик не хочет т.к. приложение постоянно
развивается и чтобы сохранять актуальность доки надо нанимать
отдельного человека, бюджета на это нет и проще и дешевле для него,
просто не менять команду. Риски очевидно есть, но не высокие ибо код
достаточно качественный.
#3 Приложение для online рекламы разрабатываемое несколькими командами
Приложение для online рекламы (опущу подробности), два года
разрабатывалось командой из десятка индусских программистов. Результат
был не то чтобы очень, что-то работало, но не все и не так. Заказчик
провел аудит кода, сократил 60% индусов и нанял команду из России
допиливать критичный кусок приложения. Также в тусовке принимают
участие отдельная группа тестировщиков из Индии и группа админов из
Калифорнии (была еще команда делающая Data Warehouse из Вьетнама, но
как-то быстро потерялась). Сам заказчик живет в Нью-Йорке. Проекту в
такой конфигурации уже скоро год и в целом все неплохо. Хотя и странно.
Без руководства разработчика и руководства администратора вся эта
конфигурация не заработала бы никогда. Да, написание документации
отнимает определенное время ежедневно, но без этого вести разработку
нереально. Что документируется:
- Общая схема компонентов и интерфейсов
- Детальное описание интерфейсов между компонентами
- Описание внешних интерфейсов
- Схема БД
- Подробное описание всех настроек системы
- Руководство как собрать и развернуть систему «с нуля»
- Зоны ответственности — кого, где и как искать если что-то случилось
#4 Документация по ГОСТ-у
Лет 10 назад я участвовал в создании комплексной системы энергоучета
которая была продана нескольким нефтяным компаниям. Энергоучет
автоматически означал поставку примерно 40 килограмм документации на
систему. Занимались написанием документов отдельно выделенные 4
человека пол года. Систему поставили, сдали сначала в опытную, а потом
и в промышленную эксплуатацию. Что характерно, все что не касалось
расключения проводов уже через 6 месяцов где-то на 10-20% не
соответствовало действительности, т.к. система постоянно
дорабатывалась. Т.е. реально ценность документации стремительно падала.
Несколько выводов
Самый простой вывод — Документации надо писать не больше, чем ее
действительно необходимо и даже если она нужна, нет смысла писать
документации больше, чем вы можете себе позволить. Поясню на примере:
Команда в 3 человека пишет приложение для заказчика. Например веб сайт.
Тратят они на это 8*3=24 часа в день. Судя по опыту в среднем на
поддержание подробного, толкового руководства разработчика в актуальном
состоянии надо не менее 2 часов в день регулярно. Что это значит
практически.
За месяц набегает примерно 600 часов разработки и 50 часов
документирования. Причем документация нужна, по большому счету в двух
случаях
- Добавляется/меняется член команды
- Меняется вендор, т.е. заказчик уходит в другую компанию
Предположим что такая ерунда случается скажем не чаще чем раз в 5
месяцев — получается, что мы тратим 5*50 = 250 часов (фактически больше
одного человеко/месяца) на то, чтобы сделать вхождение нового человека
в команду/передачу кода другой команде менее болезненной процедурой.
При этом надо понимать что наличие простой доки на 3 страницы скажем
экономит 30% на вхождение человека в проект, а даже самая
наирасподробнейшая документация видимо дает не более 50% экономии
времени — сколько документацию не читай, а в код смотреть все равно
надо.
Я мог бы еще немного по спекулировать цифрами, но думаю направление
мысли понятно и дальше Вы для своего случая досчитаете сами.
Основной тезис здесь следующий — чем более подробна документация тем
сложнее (дороже) ее поддерживать в актуальном состоянии и тем меньше
она приносит пользы в пересчете на потраченный человеко/час. Например
для типичного веб проекта — диаграмма компонентов системы, описание
настроек, интерфейсов с другими системами и т.п. очевидно полезны и код
их заменяет с трудом. Но например ценность подробной диаграммы классов
с именами методов в общем уже значительно ниже т.к. все равно придется
в код лезть и глазами смотреть.
Есть еще один аспект — написание документации, само по себе
упорядочивает понимание кода, позволяет взглянуть по продукт под другим
углом и часто в процессе написания доки можно выявить логические ляпы и
даже баги. Аудит кода и регулярные сессии рефакторинга для этого
конечно лучше подходят, но редко когда бюджета хватает и на
документирование и на аудит и на рефакторинг. Хотя конечно случается и
такое.
Антипаттерн
Очень часто, я наблюдал картину, когда тим лид или один из
разработчиков начитавшись книг и/или статей прибегал с горящими
глазами, рассказывал, что на него снизошло откровение, проект живет не
правильно и надо срочно все документировать. Далее обычно следовали два
возможных сценария
- Энтузиаста удавалось отпоить чаем, рассказать пару баек из жизни и он уходил умиротворенный
- Порыв находил выход и 4-16 часов приносились в жертву написания
подробнейшей доки подробно рассказывающей о жизни и трудовой карьере
какого-то одного класса и/или модуля приложения. Потом приходила
РАБОТА, дока забывалась и через какое-то время теряла актуальность.
Я ни в коем случае не хочу сказать что написание документации всегда
бывает бессмысленно. Здесь я говорю о спонтанных, не спланированных
приступах документирования которые достаточно часто встречаются у
разработчиков всех возрастов.
«Хватит меня путать, как собственно надо?»
Надо прежде всего думать головой и планировать документирование,
регулярный рефакторинг, аудит кода и прочие вспомогательные активности
— заранее, в комплексе и исходя из реальных потребностей и бюджета
проекта.
Любое утверждение вида:
- Документация не нужна, хорошего кода достаточно
- Надо документировать все как можно подробнее
- Надо документировать только вот это и это, все остальное нафиг
в отрыве от контекста, а именно цели проекта, бюджета проекта, состава команды, условий работы и т.д. бессмысленно.
PS: Здесь под документаций в основном понимается руководство
разработчика, но в целом выводы применимы к любым сопутствующим
текстам.
PPS: Возьмите и прочитайте доку на какую нибудь бытовую технику
(например пылесос), скорее всего Вы увидите что дока написана сразу на
несколько моделей. Возможно даже у производителей техники есть проблемы
с поддержанием актуальности, хотя может быть конечно они просто
упрощают себе логистику.
PPPS: Для mission critical систем как правило бюджет достаточно большой
и для них в 99% применимо утверждение «документировать все». Но это тем
не менее не отрицает думание головой.
|
|
Просмотров: 687 |
Добавил: Breger
| Рейтинг: 0.0/0 |
Добавлять комментарии могут только зарегистрированные пользователи. [ Регистрация | Вход ] |
 |
Copyright MyCorp © 2024 |
 |
|
