Как написать хороший проектный документ. Часть 2
Перевод статьи Angela Zhang: How to write a good software design doc
Предыдущие части: Часть 1
В первой части мы уже рассмотрели, что обязательно должен включать в себя хороший проектный документ. Пришло время действительно засесть за его написание.
Как написать проектный документ
Итак, мы уже поговорили что должен включать в себя проектный документ, а теперь пришла очередь перейти к стилю написания. Я обещаю, тут все будет иначе, чем на уроках русского языка в старшей школе.
Пишите как можно проще
Не пытайтесь писать проектный документ в формальном или научном стиле. Наша задача описать решение проблемы и получить отзывы других участником команды. Достичь простоту в написании можно с помощью:
- использования простых слов;
- коротких предложений;
- списков;
- конкретных примеров, вроде: «Пользователь Алиса подключается к своему банковскому аккаунту, и тогда…»
Добавляйте побольше графиков и диаграмм
Графики могут быть очень полезными для сравнения нескольких возможных решений, диаграммы же в принципе намного понятнее, нежели текст. Для создания диаграмм мне нравится использовать Google Drawing.
Совет от Про: не забудьте вставить ссылку на доступную для редактирования версию диаграммы под скриншотом, чтобы позже изменить её, если понадобится.
Включайте числовые показатели
Измерение проблемы очень часто её решает. Чтобы помочь оценивающим ваш проект людям получить полную картину - указывайте реальные измеряемые данные, например: количество ошибок, период ожидания и их масштаб во время использования (еще помните «О» большое и «о» малое?).
Пытайтесь быть интересным
Проектный документ — это, все-таки, не научная документация. А люди любят читать интересные вещи, так что это отличный способ сохранить вовлеченность читателя. Разумеется, всему есть предел, главное — не терять смысл.
Тест на скептицизм
Перед отправкой проектного документа другим участникам команды постарайтесь прочитать его, поменяв собственный угол “зрения”. Представьте себя в роли рецензента. Какие вопросы и неясности могут возникнуть у вас вовремя прочтения? Рассмотрите все в порядке очереди.
Тест для отпуска
Смогут ли ваши коллеги понять все правильно, как если бы вы вдруг уехали на необитаемый остров и не имели бы с ними связи?
Главная задача проектных документов — это не передача каких-то знаний, а расставление всех точек над «i» касательно проекта, а также получение оценки другими участниками.
Процесс
Проектный документ должен дать вам возможность получить мнения других людей еще до того, как вы потратите уйму времени на поиск неправильного решения неправильной проблемы. Существует множество способов получить отзывы о проекте, но об этом чуть позже. Сейчас разберемся в том, как написать проектный документ.
Прежде всего, каждый, кто участвует в проекте, должен принимать участие в создании его концепта. Это нормально, когда технически лидер принимает большинство решений, но все остальные также должны быть в курсе и принимать участие в обсуждении. Именно поэтому, мое обращение “вы” относится не к одному конкретному человеку, а ко всей команде.
Во-вторых, процесс разработки не означает, что вы начинаете все с чистого листа. Не бойтесь немного запачкать руки, взяв чужой прототип решения вашей проблемы. Это не то же самое, что писать код еще до начала разработки концепта — вот так, как раз, делать и не стоит. А использовать чужие наработки, чтобы сгенерировать собственную идею абсолютно нормально. Разумеется, чужой код должен быть только прототипом решения, поэтому не стоит включать его в основную часть.
После того, как вы будете готовы к генерированию идей, следуйте следующим рекомендациям:
1. Попросите своего тех-лида оценить ваши наработки. В идеале, роль рецензента лучше отдать человеку, хорошо разбирающемуся в данной проблеме.
2. Засядьте в зале переговоров с доской.
3. Точно опишите проблему, которую вы хотите исправить (ни в коем случае не пропускайте этот пункт!)
4. Затем объясните как вы планируете её исправить и почему именно это решение наиболее верно.
И обязательно сделайте это еще до написания проектного документа. Так вы получите отзывы как можно быстрее, еще до инвестирования своего времени и психологической привязанности к какому либо решению. Очень часто, если ваши мысли по поводу решения остаются теми же, рецензент сможет указать вам на слабые места и возможные трудности, которые могут возникнуть по ходу дела.
После того, как вы напишете черновик проектного документа — дайте его просмотреть коллегам. И не забудьте вставить их имена в раздел «Названия и разработчики», если они внесли свой вклад. Это дополнительно поощрит и смотивирует вашего рецензента.
Если вы или рецензенты вносите свои коррективы — обязательно делитесь этим с другими учатсниками проекта, для дополнительной оценки. Я предпочитаю ограничивать время на сбор обратной связи примерно неделей, чтобы исключить длительные задержки. Обращайте внимания на все комментарии, которые оставляют люди в течение этой недели. Оставить хотя бы один комментарий без внимания = плохая карма.
И последнее, если между вами, вашими рецензентами и другими инженерами, читающими этот документ, много разногласий — я настоятельно рекомендую расставить все точки над «i» в разделе Дискуссии. Затем, организуйте встречу с каждой стороной и обговорите все лично.
Как правило, если одна тема насчитывает больше 5 комментариев — личная встреча намного эффективнее. Помните, что вы ответственны за конечный результат, даже если не сможете прийти к консенсусу.
Недавно я разговаривал с Shrey Banga об этом, и узнал, что в Quip (известное ПО) используется аналогичная стратегия, с отличием лишь в том, что они вовлекают также опытных инженеров и тех-лидов из других команд. Я пока так еще не делал, но мне кажется, что в этом есть смысл. Ведь так можно получить мнение разных людей, которые видят все под другим углом, а также улучшить читабельность проектного документа.
Если вы сделали все, что я описал выше, значит пришло время погрузиться в разработку! И еще раз, не забывайте во время реализации постоянно использовать проектный документ, обновляя информацию по мере изменений в проекте. Так вы сможете совершенствоваться. Позже, вы обязательно меня поблагодарите за то, что вам не приходится все время объяснять отдельные части проекта с другим участникам команды.
И наконец, давайте будем реально оценивать работу: какую бы вы оценку дали вашему проектному документу?
Мой коллега Кент Ракип дал как-то раз хороший ответ на этот вопрос. Проектный документ можно считать успешным, если он финансово окупается. Впрочем, бывает, что все может привести и к такому результату, как например:
1. Вы проводите 5 дней за созданием проектного документа, постепенно проходя через всю техническую архитектуру
2. Получаете отзывы от рецензентов о том, что X является самой рискованной частью проекта
3. Вы занимаетесь устранением проблемы X
4. Через 3 дня вы выясните, что исправить X либо невозможно, либо намного сложнее, чем первоначально предполагалось
5. Решаете прекратить работу над этим проектом и вместо него занимаетесь другим.
В начале этой статьи я сказал, что цель проектного документа в том, что “правильная” работа будет выполнена. Благодаря этому вышеприведенному в пример проекту, вы поняли, что вполне нормально отложить проект еще на начальной стадии, потратив только 8 дней, вместо месяца или больше. По-моему, это тоже неплохой результат.
