Как написать хороший документ по дизайну программного обеспечения

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

Эта статья - моя попытка описать, что делает дизайн-документ отличным .

Статья разбита на 4 раздела:

  • Зачем писать дизайн-документ
  • Что включить в дизайнерский документ
  • Как это написать
  • Процесс вокруг него

Зачем писать дизайн-документ?

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

Уже есть много статей о том, почему так важно написать проектную документацию перед тем, как погрузиться в кодирование. Итак, все, что я скажу здесь:

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

Основная цель дизайнерской документации - сделать вас более эффективными, заставив вас продумать дизайн и собрать отзывы других. Люди часто думают, что цель проектной документации - научить других о какой-либо системе или служить документацией позже. Хотя это могут быть полезные побочные эффекты, они не являются целью сами по себе.

Как правило, если вы работаете над проектом, который может занять 1 инженерный месяц или больше, вам следует написать проектную документацию. Но не останавливайтесь на достигнутом - многие небольшие проекты тоже могут выиграть от мини-документации по дизайну.

Большой! Если вы все еще читаете, вы верите в важность дизайнерской документации. Однако разные инженерные команды и даже инженеры в одной команде часто пишут проектную документацию по-разному. Итак, давайте поговорим о содержании, стиле и процессе создания хорошей дизайнерской документации.

Что включить в дизайн-документ?

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

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

Название и люди

Заголовок вашего дизайнерского документа,автор (ы) (должен совпадать со списком людей, планирующих работать над этим проектом), рецензент (ы)документа (мы поговорим об этом подробнее в разделе «Процессы» ниже) и дату последнего обновления этого документа.

Обзор

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

Контекст

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

Цели и не-цели

Раздел Цели должен:

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

Нецели одинаково важны для описания того, какие проблемы вы не будете решать, чтобы все были на одной странице.

Вехи

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

Используйте календарные даты, чтобы учитывать несвязанные задержки, отпуска, встречи и т. Д. Это должно выглядеть примерно так:

Start Date: June 7, 2018

Milestone 1 — New system MVP running in dark-mode: June 28, 2018

Milestone 2 - Retire old system: July 4th, 2018

End Date: Add feature X, Y, Z to new system: July 14th, 2018

Добавьте [Update]здесь подраздел, если ETA некоторых из этих этапов изменится, чтобы заинтересованные стороны могли легко увидеть самые свежие оценки.

Существующее решение

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

пользовательисторияотличный способ обрамить это. Имейте в виду, что в вашей системе могут быть разные типы пользователей с разными вариантами использования.

Предложенное решение

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

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

Альтернативные решения

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

Возможность тестирования, мониторинг и оповещение

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

Межкомандное влияние

Как это увеличит нагрузку на вызовы и разработчиков?

Сколько это будет стоить денег?

Вызывает ли это регресс задержки в системе?

Есть ли уязвимости в системе безопасности?

Какие есть негативные последствия и побочные эффекты?

Как служба поддержки может сообщить об этом клиентам?

Открытые вопросы

Любые нерешенные вопросы, в которых вы не уверены, спорные решения, которые вы хотели бы услышать от читателей, предложения о будущей работе и т. Д. Ироничное название этого раздела - «известные неизвестные».

Подробный обзор и сроки

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

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

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

Как это написать

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

Напишите как можно проще

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

  • Простые слова
  • Короткие предложения
  • Маркированные списки и / или нумерованные списки
  • Конкретные примеры, такие как «Пользователь Алиса подключает свой банковский счет, а затем…»

Добавьте множество диаграмм и диаграмм

Диаграммы часто могут быть полезны для сравнения нескольких возможных вариантов, а диаграммы, как правило, легче анализировать, чем текст. Мне повезло с Google Drawing для создания диаграмм.

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

Включите числа

Масштаб проблемы часто определяет решение. Чтобы помочь рецензентам получить представление о состоянии мира, включите реальные числа, такие как количество строк БД, количество пользовательских ошибок, задержка и то, как они масштабируются с использованием. Помните ваши обозначения Big-O?

Постарайся быть смешным

Спецификация - это не академическая статья. Кроме того, людям нравится читать смешные вещи, так что это хороший способ заинтересовать читателя. Однако не переусердствуйте до того, чтобы отойти от основной идеи.

Если вы, как я, есть проблема , смешно, Джоэл Спольски ( очевидно , известный своими комедийными талантами ...) имеет этот совет:

Один из самых простых способов быть забавным - это быть конкретным, когда это не требуется [… Пример:] Вместо того, чтобы говорить «особые интересы», скажите «леворукие фермеры, выращивающие авакадо».

Выполните тест Skeptic

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

Пройти тест на отпуск

Если вы сейчас отправляетесь в длительный отпуск без доступа к Интернету, может ли кто-нибудь из вашей команды прочитать документ и реализовать его так, как вы планировали?

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

Процесс

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

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

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

После этого, когда вы начнете понимать, как реализовать свой проект, сделайте следующее:

  1. Попросите опытного инженера или технического руководителя вашей команды выступить в роли рецензента. В идеале это должен быть кто-то, кого уважают и / или знакомы с крайними случаями проблемы. При необходимости подкупите их бобой.
  2. Войдите в конференц-зал с доской.
  3. Опишите проблему, которую вы решаете, этому инженеру (это очень важный шаг, не пропускайте его!).
  4. Затем объясните реализацию, которую вы имеете в виду, и убедите их, что это правильный вариант.

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

Затем, после того, как вы написали черновик своего проектного документа, попросите того же рецензента прочитать его еще раз и проштампуйте его, добавив свое имя в качестве рецензента в раздел « Заголовок» и «Люди » проектной документации. Это создает дополнительный стимул и ответственность для рецензента.

В этой связи рассмотрите возможность добавления специализированных рецензентов (таких как SRE и инженеры по безопасности) для конкретных аспектов проекта.

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

Наконец, если между вами, вашим рецензентом и другими инженерами, читающими документ, возникают серьезные разногласия, я настоятельно рекомендую объединить все разногласия в разделе « Обсуждение » вашего документа. Затем назначьте встречу с разными сторонами, чтобы обсудить эти разногласия лично.

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

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

После того, как вы сделали все вышеперечисленное, пора приступить к реализации! Чтобы получить дополнительные преимущества, рассматривайте этот документ по дизайну как живой документ по мере реализации дизайна . Обновляйте документ каждый раз, когда вы узнаете что-то, что заставляет вас вносить изменения в исходное решение или обновлять область видимости. Вы будете благодарить меня позже, когда вам не придется снова и снова объяснять вещи всем заинтересованным сторонам.

Наконец, давайте на секунду перейдем к настоящей мете: как мы оцениваем успех дизайнерской документации?

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

  1. Вы тратите 5 дней на написание дизайн-документации, это заставляет вас продумывать разные части технической архитектуры.
  2. Вы получаете отзывы от рецензентов, которые Xявляются самой рискованной частью предлагаемой архитектуры.
  3. Вы решили внедрить в Xпервую очередь, чтобы снизить риски проекта
  4. Через 3 дня вы понимаете, что Xэто либо невозможно, либо намного сложнее, чем вы изначально планировали.
  5. Вы решили прекратить работу над этим проектом и вместо этого сделать другую работу приоритетной.

В начале этой статьи мы сказали, что цель дизайнерской документации - обеспечить выполнение правильной работы. В приведенном выше примере благодаря этой проектной документации вместо того, чтобы тратить потенциально месяцы только на то, чтобы прервать этот проект позже, вы потратили только 8 дней. Мне кажется, это довольно удачный результат.

Пожалуйста, оставьте комментарий ниже, если у вас есть какие-либо вопросы или отзывы! Я также хотел бы услышать о том, как вы по-другому разрабатываете документацию в своей команде.

Отдавая должное там, где нужно отдать должное, я многому научился из вышеперечисленного, работая вместе с некоторыми невероятными инженерами в Plaid (мы нанимаем! Приходите проектировать и строить вместе с нами несколько замечательных технических систем) и Quora.

Если вам понравился этот пост, подпишитесь на меня в Твиттере, чтобы увидеть больше сообщений о проектировании, процессах и серверных системах.