Введение
Любой успешный проект начинается с ясного и понятного плана, который определяет направление работы и описывает подход к его реализации. Проработка проекта на ранних этапах с достаточным уровнем детализации экономит время во время разработки и позволяет успешно завершить проект в предсказанные сроки и бюджет. Именно для этой цели и созданы технические дизайн документы ("design doc" или "дизайн док"). Дизайн документы помогают разработчикам понимать основные требования к проекту, его архитектуру и функциональные возможности, а также процессы обеспечения безопасности и отказоустойчивости, масштабирования и эксплуатации.
Хороший технический документ может стать ключевым инструментом для общения и взаимодействия между разработчиками, менеджерами проекта и другими заинтересованными сторонами. Он помогает улучшить понимание целей проекта, улучшить качество продукта и сократить время, затраченное на разработку.
В этой статье мы рассмотрим, что такое дизайн документы, зачем они нужны и как их создавать с максимальной пользой для проекта.
Зачем нужны дизайн документы?
Не секрет, что отмерить стоит семь раз, а отрезать только единожды. В разработке этот принцип проявляется как нельзя хорошо. Неверно заложенная архитектура проекта в начале может привести к серьёзным проблемам в будущем.
В связи с этим есть несколько причин, по которым важно писать дизайн документы.
Уточнение требований. Любая техническая задача начинается с требований. Явно прописанные требования и ограничения определяют принимаемые решения. Технические документы помогают уточнить и явно зафиксировать требования к проекту и определить, какие функции и возможности должны быть реализованы.
Коммуникация. Дизайн документы служат средством коммуникации между инженерами и другими членами команды. Они помогают убедиться, что все заинтересованные стороны понимают проект одинаково. Дизайн документы помогают лучше проработать проект, когда в него вовлечены разные подсистемы и ответственные за них люди, а общего понимания как все подсистемы работают вместе в деталях нет ни у кого.
Улучшение качества. Одна голова хорошо, а две лучше. Технические документы позволяют обнаружить потенциальные проблемы и ошибки в проекте еще до его начала. Куда намного проще переписать текст или перерисовать диаграмму, чем переделывать запущенную техническую систему. Это позволяет снизить риски и улучшить качество результата.
Сохранение знаний. Технические документы после финализации естественным образом становятся документацией и источником знаний о технической системе. С помощью дизайн документов получается сохранять информацию и передавать её новым людям. Также они позволяют фиксировать мотивацию принятых тех или иных решений на будущее.
В целом, технический дизайн документы помогают командам разработчиков эффективно проектировать проекты, улучшать качество продукта и снижать риски и ошибки в процессе разработки.
Что должно быть в хорошем дизайн документе?
У хорошего дизайн документа должна быть структура и формат. Технический документ - это не пример художественной литературы. Поэтому лучше придерживаться единообразной структуры.
Цель. Любая работа начинается с целеполагания. Всегда важно понимать, чего нам нужно достичь.
Требования. Важно прописать требования в явном виде в самом начале. Именно требования определяют дальнейший дизайн системы и работу по проекту. Все требования можно разбить на 2 блока: функциональные и не функциональные. К функциональным относится описание того, как должна работать система, какие функции предоставлять. Нефункциональные требования - это часто ограничения, предъявляемые к системе. Нефункциональные требования касаются таких вопросов, как масштабируемость, производительность, надежность и отказоустойчивость, безопасность, сложность и стоимость поддержки. Также в требованиях стоит прописать ожидаемый уровень нагрузки, количество запросов, объема и количества хранимых и передаваемых данных.
Текущее состояние. Часто бывает, что нужно не с нуля спроектировать новый сервис, а внести изменения в существующий. В данной секции полезно раскрыть текущее положение дел, предоставить схему взаимодействия подсистем и обратить отдельное внимание на проблемные места, которые надо переделать или улучшить. В целом в данной секции мы описываем почему в данный момент существующая система не отвечает предъявляемым требованиям и подводим к тому, что в системе надо изменить.
Обзор альтернативных решений.
Редко бывает, что есть одно правильное и очевидное решение проблемы. Обычно существует множество альтернатив, и у каждой из них есть плюсы и минусы. Вообще всё инженерное дело строится на поиске баланса между достоинствами и недостатками разных подходов и оценке последующих рисков и последствий принятия технических решений. Поэтому важно зафиксировать рассмотренные альтернативные подходы и описать их за и против. Это полезно как для читателей в моменте обсуждения выбранного решения, потому что может снять их вопросы. Так и для истории на будущее, чтобы вспомнить почему было принято определенное решение, а не взято альтернативное.
Предлагаемое решение. Данная секция описывает то, как вы предлагаете достигать исходную цель, учитывая вышеописанные требования. К этому моменту уже есть достаточно хорошее понимание, что надо сделать, какие есть проблемы и как их можно решать. Эта секция отличается от проекта к проекту. В некоторых она должна быть сфокусирована на верхнеуровневой картине архитектуры и взаимодействии разных сервисов и систем хранения данных друг с другом. В других может быть больше погружения в детали кода, алгоритмов или проектирования API. В этой секции я бы всегда рекомендовал строить повествование от большего к малому. Сначала дизайн описывается поверхностно, и далее по ходу текста происходит уточнение и погружение в детали. Также очень полезно прикреплять графические материалы в виде диаграмм или иных изображений. Человеческий мозг так устроен, что одна хорошая визуализация может раскрыть суть лучше тысячи слов.
Безопасность и конфиденциальность. Данная секция зависит от проекта и не в каждом документе является обязательной., Но если вы собираете и храните данные, то стоит задуматься о выполнении требований законодательства стран, где будет работать сервис. Стоит явно продумать и прописать планы по обеспечению безопасности и конфиденциальности собранных и производных данных, включая политики и процедуры работы с ними. Если ваша система будет принимать контент, создаваемый пользователями (user generated content), стоит заложить возможность модерации такого контента. Если вы позволяете постить фото или видео, очень быстро появятся те, кто начнет загружать взрослый контент. Если вы позволяете публиковать текст, вскоре появятся те, кто будут постить ссылки на разного рода фродерские и просто сомнительные ресурсы. Также стоит помнить, что система должна поддерживать право на забвение и удаление контента по требованию автора. В случае предоставления публичного доступа к сервису из интернета, надо отдельно продумать риски эксплуатации дыр в безопасности.
Производительность и отказоустойчивость. Обязательный пункт, если вы делаете комплексную систему или новый сервис. По идее в требованиях должны быть прописан уровень доступности сервиса и какой SLO вы должны выполнять. Я бы рекомендовал сразу фиксировать цели по доступности и производительности ещё до начала проекта. Потому что в дальнейшем может случиться так, что вы в них не попадаете, а их выполнение требует значительных доработок и переделок. Куда проще обдумать это заранее и сразу учитывать в своей архитектуре.
Стоимость. Достаточно важный аспект, который нельзя забывать. Стоимость можно разбить на несколько компонент: стоимость инфраструктуры, разработки, поддержки и расширения. Стоимость инфраструктуры оценить достаточно просто, посчитав количество необходимого железа под описанные требования и нагрузку. Стоимость разработки уже чуть сложнее, т.к. необходимо прикинуть объем работ и количество людей, которые смогут завершить проект к ожидаемому сроку. А вот цена поддержки и расширения системы - это вопрос оценки пути развития функциональности. И если в случае поддержки нужно думать об автоматизации и ускорении ручных действий, то для проектирования системы с учетом дальнейшего развития стоит полагаться на здравый смысл и иметь продуктовое представление будущего проекта. С одной стороны любая дополнительная работа сделанная заранее увеличивает сроки и стоимость проекта. С другой стороны если можно относительно дёшево заложить расширяемость под будущее развитие, стоит это сразу держать в голове и заложить изначально.
Масштабируемость. Важно иметь план как будет масштабироваться система в случае увеличения нагрузки и просто во время своей жизнедеятельности. Будет ли это простой и рутинный процесс добавления железа или же сложный процесс, требующий инженерных доработок? Есть ли понимание как можно масштабировать каждый из компонентов системы? Понятно, что увеличение нагрузки на порядки не всегда имеет смысла закладывать сразу - всё имеет свою цену. Но иметь план по масштабированию системы в 2-5 раз от обычных рабочих нагрузок стоит.
План реализации проекта. Необязательно иметь детальный список задач со ссылками на тикеты в Jira. Но иметь очень поверхностное и верхне уровневое представление какие этапы будут в проекте, какие у них зависимости и в каком порядке их нужно делать полезно. Что нужно сделать и какие ресурсы для этого нужны важно для старта работ по проекту.
Ревьюеры. Я рекомендую всегда включать в документ список ревьюеров, от кого вы ожидаете явную обратную связь или согласие с предложенным решением. Без этого сложно понять ознакомились ли люди с документом и согласны ли они с тем, что там изложено. Если же они ставят галочку напротив своего имени, то явно коммуницируют, что с их стороны вопросов нет и они согласны с предложенным дизайном.
Список полезных ссылок. Если вы производили обзор существующих решений и анализ подходов других людей или компаний, то у вас есть список ресурсов. Я рекомендую включаться ссылки на эти ресурсы в итоговый документ. Это позволит в будущем не искать их снова, а иметь связанные с темой документа ссылки под рукой.
Конечный набор разделов документа может варьироваться в зависимости от конкретного проекта. Но, на мой взгляд, вышеописанные секции являются более менее стандартными. Понятно, что не всегда нужно включать информацию по всем пунктам, но держать в голове под какими углами надо посмотреть на проект однозначно стоит.
На что ещё обращать внимание при написании дизайн документов?
Любой дизайн документ начинается с подготовительной работы. Часто в начале проекта совершенно не ясно что и как нужно сделать. И написание документа обычно хороший сдерживающий фактор сразу броситься писать код и наломать дров. Для начала надо в голове разложить по полочкам, что и как будет сделано. Пишется технический документ обычно не в один присест.
Первым шагом обычно стоит описать разделы про цель и требования. Далее можно посмотреть на них и задаться вопросом, а что нам не хватает в текущей системе? После погружения в текущие реалии существующей системы полезно зафиксировать это в секции "Текущее состояние". Этот шаг особенно актуален, если не вы изначально проектировали исходную систему или не имеете глубокое погружение в неё.
К этому моменту у вас наверняка появятся идеи, что нужно сделать, чтобы добиться поставленной цели. Часто полезно в этот момент перейти к исследовательской фазе. А давайте посмотрим, а как ту же самую проблему решали другие люди. С этим может помочь простой поиск любых материалов по теме: выступления на конференциях, публикации на профильных сайтах, исследовательские работы. Очень часто проблема не уникальна и другие люди уже решали её до вас. Обычно компании любят делиться своим опытов в своих технических блогах, которые становится кладезем полезной информации. После обзора альтернатив в голове уже есть картина возможных подходов, плюсов и минусов каждого подхода, а также предпочитаемый путь решения проблемы в контексте реалий вашей технической системы. Пора переходить к написанию секций про альтернативы и выбранное техническое решение.
Также еще несколько рекомендаций, на что стоит обращать внимание при написании технического документа:
Краткость - сестра таланта. Чего точно стоит избегать, так длинных и пространных текстов. Не стоит пытаться впечатлить читателей скрытым талантом писателя и повторять успех романа "Война и мир". К сожалению, бывает сложно уместить весь документ и его смысл в одну страницу печатного текста. Но дизайн документы длиною в десятки страниц долго читать, сложно удержать контекст и просто трудно заставить коллег вникнуть и оставить осмысленный фидбек. Поэтому нужно стараться писать настолько кратко, насколько это возможно без потери смысла и цели документа.
Простой и понятный язык. Нет ничего более утомительного, чем читать длинные и сложные предложения длиною в абзац. Если к концу предложения забываешь, что было в начале, это усложняет восприятие. Я бы рекомендовал писать кратко, просто и понятно. Отдельно стоит отметить документы на не родном языке (например, английском). Точно стоит избегать желание впихнуть всю ту новую лексику, которую вы недавно усвоили на языковых курсах. Не стоит усложнять жизнь себе и коллегам. Выражайте мысли максимально простыми и общеизвестными словами и выражениями.
Помни про читателя. Я бы рекомендовал всегда помнить о том, кто будет читать документ. Несмотря на то, что чаще всего это коллеги технические специалисты, но у всех может быть разный бэкграунд и опыт работы с вашей системой. Читателю должно быть понятно какую проблемы вы решаете, какие сложности есть и какое решение вы предлагаете. Очень плохо, если вашим коллегам ничего не ясно после прочтения документа. Хорошо, если по ходу повествования описываете и раскрываете важные для понимания нюансы. Это может быть сложно, но важно писать документ с прицелом, что читать его будут люди, не настолько погруженные в контекст, как вы.
Иллюстрации. Мозг человека устроен так, что ему проще воспринимать визуальные образы, чем текст. Если возможно заменить страницу текста одной диаграммой, с неё однозначно стоит начать повествование. Я встречал достаточно удачные почти одно страничные дизайн документы, где основным контентом было визуальное представление. А текстом давались небольшие пояснения и уточнения. Такой подход очень упрощает понимание и быстрее погружает в контекст предлагаемого решения.
Списки и перечисления. Не стоит бояться сухих и кратких списков с простыми перечислениями тезисов, где это применимо. Далеко не обязательно писать абзацы текста, чтобы перечислить, например, плюсы и минусы подхода. Порою нескольких слов может быть достаточно, чтобы передать смысл. Ведь читатели ваши же коллеги, внутри контекста и также знакомы с тем, о чем вы пишите.
Заключение
Ну и в заключение я хотел бы привести несколько примеров публичных дизайн документов, которые можно использовать для вдохновения в своей работе:
Спасибо за внимание и успешного написания технических дизайн документов!