четверг, мая 01, 2008

What do you need to know

Как вести проектную документацию? Оставим в стороне ГОСТы, RUP, фантазии некомпетентных и прочую фигню и сосредоточимся на одном вопросе: "Какая документация вам нужна в проекте, рассчитанном на несколько лет?" Проекты в стиле "Сделал и забыл" (а это большая часть аутсорсинга) в документации не нуждаются и останутся за скобками. Итак, поехали:

Первое, что нам нужно, это требования. У натуралистов есть такое правило: "Не записано ― не наблюдалось" Это именно то, чем стоит руководствоваться при работе с требованиями. Почему это важно? Да потому, что без требований "в бумаге" через три месяца вы не сможете отличить баг от реально затребованной кем-то фичи, через полгода у вас появятся "гуру" обладающие редким знанием о том, что именно и зачем вы делаете, через три года вы обзаведетесь прекрасными образцами устного фольклора, которые останутся единственным источником информации об истории проекта, а через пять лет, когда вы захотите все переписать с использованием современных технологий, вам придется нанять археолога.

Как именно работать с требованиями много говорили и без меня. Единственное, что стоит отметить: чем глубже проанализированы требования, тем легче. Требование "заказчик хочет зеленую кнопку" менее ценно чем "интерфейс должен, по возможности, соответствовать программе X с которой у пользователей есть опыт работы". В случае, если кнопку не удастся сделать зеленой, хотя бы понятно с какой стороны начинать переговоры по поиску компромисса.

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

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