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