Как создавать эффективные документы по внешнему дизайну

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

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

:::информация Следующая статья была слегка отредактирована ИИ для улучшения грамматики и ясности.

:::

Содержание

• Зачем нам нужны проектные документы внешнего интерфейса?
• Причина 5. Личные интересы.
• Причина 4. Создайте историю проекта.
• Причина 3. Снижение риска «автобусного фактора».
• Причина 2. Распространение работы.
• Причина 1. Объединяйте заинтересованные стороны.
• Тип проектной документации
• Дизайн высокого уровня (HLD)
• Низкоуровневый (детальный) дизайн
• Техническое видение
• Техническая стратегия
• Шаблон оформления внешнего интерфейса
• Заключение

Зачем нам нужна проектная документация переднего плана?

Причина 1. Объединяйте заинтересованные стороны

Огромная сила письменного слова значительно затрудняет неправильное понимание друг друга.

Путь штатного инженера

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

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

Представьте, что за месяц до даты запуска вы обнаружите, что новый API, с которым вам нужно интегрироваться, ведет себя не так, как вы ожидали, или возвращает другой результат. Я вспоминаю пример из моей работы в AWS, когда нашей команде внешнего интерфейса нужно было интегрировать с API стороннего сервиса.

Мы ожидали увидеть некоторую важную информацию, отображаемую как часть ARN ресурса, но сторонняя группа ожидала, что мы вызовем дополнительный API для описания ресурса. Однако мы не смогли сделать дополнительный вызов из-за проблем с производительностью (нам нужно было отобразить в списке тысячи ресурсов), что вызвало цепочку эскалаций, включающую UX-дизайн, нашу группу бэкэнда службы, внешнюю команду службы, цепочку менеджеров. , и руководитель фронтенда (я). Этой проблемы можно было бы избежать, если бы мы заранее проверили дизайн-документ.

Причина №2: Распространение работы

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

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

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

Причина № 3: снижение риска «автобусного фактора»

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

Причина № 4: Создайте историю проекта

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

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

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

Причина № 5: личные интересы

Еще одна причина, по которой проектная документация имеет решающее значение, – личные интересы. Если вы стремитесь к продвижению по службе или хотите продемонстрировать свой вклад в компанию, наличие хорошо документированного проектного документа может быть чрезвычайно полезным. Хотя список отправленных PR может продемонстрировать ваши технические навыки, он не свидетельствует о вашей способности управлять проектом, руководить командой, планировать работу или решать сложные проблемы.

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

Типы проектной документации

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

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

Дизайн высокого уровня (HLD)

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

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

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

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

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

В этом документе вам может быть интересно выделить следующее:

• Вехи проекта (например, "Создание виджета редактора политик JSON", "Создание процесса копирования между регионами" и т. д.)

* Для каждой вехи определите высокоуровневое дерево компонентов с проблемами, связанными с состоянием (если вы используете систему управления состоянием, такую ​​​​как Redux, может быть важно выделить, какие данные попадают в глобальное состояние, а какие данные изолированы в локальное состояние компонента).

* Если вы используете распределенную архитектуру интерфейса (микро-интерфейсы), вы можете применить Domain-Driven Design для установления новых границ в архитектуре. Другими словами, вписывается ли эта новая функция в существующий субдомен/ограниченный контекст или требует разработки и развертывания совершенно нового микроинтерфейсного приложения. Если второе, то как оно будет взаимодействовать с другими приложениями и какие события будут представлять эти коммуникационные проблемы?

* Модель интеграции и разрешений API: какие разрешения требуются для вызова определенного API и как будет вести себя UX в случае отсутствия разрешений (например, перенаправление на страницу B)

* Известные ограничения и неопределенности (например, «Мы не сможем использовать компонент ModalA, так как для создания представления требуются права учетной записи администратора. аккаунт» или «Если мы решим использовать тот же расширенный редактор JSON, что и на странице A, нам нужно изучить, как мы можем управлять общими сторонними зависимостями в будущем»). Такое рассмотрение может быть очень полезно для инженеров, которые будут тесно работать над низкоуровневым дизайном для этой вехи.

* Определите бизнес/операционные показатели для отслеживания

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

Документы по дизайну высокого уровня часто проверяются несколько раз, чтобы убедиться, что все функции высокого уровня реализуемы в заданные сроки. В процессе обзора заинтересованные стороны могут определить, какие функции можно вырезать, а какие должны быть приоритетными для запуска на следующем этапе проекта. Этот следующий этап может быть представлен различными вехами, такими как «Предварительный просмотр GA -> Полная общедоступность» или «Самый ценный игрок —> v1 -> v2». Хотя знать точные временные рамки этих этапов может и не обязательно, важно иметь четкое представление о бизнес-ценности каждого этапа и о том, как он соотносится с общими целями проекта.

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

Низкоуровневый (детальный) дизайн

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

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

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

Какие детали вы можете включить в свой проектный документ:

• Расширенное дерево компонентов с более детализированными компонентами и четко определенными формами состояний и контрактами компонентов.
• Если вашему приложению требуется сложная оркестровка API, вам может пригодиться подробная блок-схема, на которой показано порядок выполнения API и когда обновлять компоненты с новым состоянием.
• Обработка ошибок для особых случаев использования
• Проблемы производительности, такие как кэширование и оптимизация сети.
• Проблемы безопасности, такие как схемы разрешений для общего доступа, хранение конфиденциальной информации в локальном хранилище/IndexDB, защита CSRF, заголовки CSP
• Соображения об альтернативном дизайне
• Технологии и инструменты, которые следует использовать
• Сценарии тестирования (обычно здесь речь идет о тестах E2E)
• Точная оценка работы и уровня распараллеливания

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

Техническое видение

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

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

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

Не существует определенного стандарта того, как выглядит видение. Это может включать:

• Архитектура проекта высокого уровня
• Набор руководств и принципов для команды или всей организации (например, рекомендации по тестированию, видение формы Redux, применение дизайна с разделением функций и т. д.)
• Сводка принимаемых решений
• Определение процессов (например, ротация дежурных по вызову, устранение технического долга и т. д.)

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

Техническая стратегия

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

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

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

Шаблон оформления внешнего интерфейса

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

Метаданные проекта

Метаданные проекта — это важная информация о документе, которая обеспечивает контекст и помогает в управлении версиями. Сюда входят имя автора, дата создания документа, дата последнего изменения и текущий статус документа (например, «Черновик», «Просмотрено» или «Отклонено»). Если документ является низкоуровневым проектом, он также может содержать ссылку на высокоуровневый проектный документ для справки.

Мотивация

Раздел мотивации дизайнерского документа должен содержать краткий обзор проблемы, на решение которой направлена ​​функция или проект. Он должен быть сосредоточен на «что», а не на «как», и может состоять всего из нескольких предложений. Цель этого раздела — предоставить контекст и подготовить почву для остальной части документа. Не включайте сюда детали реализации вашего дизайна и дизайнерское/техническое решение — это будет рассмотрено позже в документе.

Терминология

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

Предложение по дизайну

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

Как упоминалось ранее, визуальные диаграммы — эффективный способ передать сложные идеи. Например, в моей недавней статье я показываю, как создать диаграмму инфраструктуры с помощью AWS Application Composer всего за несколько кликов. Этот инструмент может быть чрезвычайно полезен для создания четких и кратких архитектурных диаграмм, которые эффективно передают ваш проект. Кроме того, это может помочь вам создать Proof of Concept для вашей архитектуры, с которой ваши коллеги смогут взаимодействовать.

Альтернативные варианты дизайна

В разделе «Рассмотренные альтернативы» вы демонстрируете (себе и другим!), что вы здесь, чтобы решить проблему, а не просто в восторге от решения. Если вы обнаружите, что пропускаете этот раздел, потому что вы не рассматривали никаких альтернатив, это сигнал о том, что вы, возможно, не продумали проблему до конца.

Путь штатного инженера

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

Соображения риска

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

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

Соображения безопасности

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

Операции

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

Сценарий тестирования

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

Приложения

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

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

Заключение

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

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

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

:::информация Первоначально опубликовано на https://thesametech.com< /em> 30 апреля 2023 г.

:::

Вы также можете подписаться на меня в Twitter и подключитесь к LinkedIn чтобы получать уведомления о новых сообщениях!