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

1656580948 kak napisat horoshij dokument o dizajne programmnogo obespecheniya

Анжела Чжан

ymTYK-Zftvwl9CnOYL5uPml36Ps4OYeLe6Ma
Фото Эсте Янсенс на Unsplash

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

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

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

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

Зачем писать проект?

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

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

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

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

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

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

gj8fgseDg1J1gal9FQHJFTkKAMMGZN8XznjK
Фото Тодда Квакенбуша на Unsplash

Что включать в проектный документ?

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

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

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

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

Обзор

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

Контекст

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

Цели и нецелые

Раздел Цели имеет:

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

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

Вехи

Список контрольных точек, которые можно измерить, чтобы ваш PM и менеджер вашего менеджера могли просмотреть его и приблизительно знать, когда будут выполнены разные части проекта. Я призываю вас разбить проект на основные этапы, с которыми сталкиваются пользователи, если проект длится более 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] в этом подразделе, если приблизительное время ожидания некоторых из этих этапов изменится, чтобы заинтересованные стороны могли легко увидеть новейшие оценки.

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

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

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

Предлагаемое решение

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

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

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

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

Проверка, мониторинг и оповещение

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

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

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

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

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

Подробный объем и временной график

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

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

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

sGfVXpLpPjAP4aeejy0Sul3KviBKiX6kojUO
Фото от rawpixel на Unsplash

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

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

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

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

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

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

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

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

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

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

Старайтесь быть смешными

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

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

Один из самых простых способов быть смешным – это быть специфический когда это не нужно [… Example:] Вместо того чтобы говорить «особые интересы», скажите «львовые фермеры авакадо».

Сделайте Скептический тест

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

Сделайте Тест на отпуск

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

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

vqucQKHbe0zhgV9DZiEwWmogFhFzZTROdxAc
Фото от SpaceX на Unsplash

Процесс

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *