Это перевд статьи https://eng.lyft.com/awesome-tech-specs-86eea8e45bb9.
Рассмотрим следующие кошмарные сценарии.
Вы собираетесь запустить новую функцию, над которой ваша команда работала несколько недель. Когда вы пытаетесь проверить ее на стадии стейджинга, ничего не работает так, как ожидалось. После изучения проблемы вы обнаруживаете, что ваша функция зависит от сервиса, который другая команда недавно упразднила.
Пытаясь интегрировать клиентскую и серверную работу для новой функции в вашем приложении, вы обнаруживаете, что инженер-клиент работал на основе устаревшей технической спецификации, что обесценивает недели его работы.
После объявления о том, что ваша команда работает над новой функцией, вы получаете множество запросов на расширение области проекта. Загруженный новыми требованиями, вы начинаете сомневаться, будет ли функция когда-либо внедрена в производство.
Что общего у этих кошмарных сценариев? Каждый из них мог бы быть предотвращен благодаря потрясающей технической спецификации: документу, обычно написанному инженером, который описывает, как будет работать функция, проект или сервис с технической точки зрения.
Сама идея технической спецификации может казаться противоречащей этике Кремниевой долины. Двигайтесь быстро - ломайте вещи - быстро итерируйте - будьте исполнителем. Зачем тратить время на написание, распространение и обновление технической спецификации, когда это время можно было бы потратить на ее реальное создание?
Но технические спецификации имеют больше пользы, чем осознают большинство инженеров. Обдуманная, хорошо написанная техническая спецификация открывает множество преимуществ, таких как:
(Почти) Безбаговые релизы
Тщательная техническая спецификация раскрывает широкие идеи (и часто детали низкоуровневой реализации, такие как имена конечных точек и коды ошибок) для широкой аудитории, максимизируя вероятность того, что баг или регрессия будут обнаружены раньше, а не позже. Всегда есть неожиданные баги, но хорошая техническая спецификация может устранить большинство из них, привлекая множество глаз к вашему предложению.
Документация
Ваша техническая спецификация служит документацией как во время реализации функции, так и после запуска функции. Во время реализации функции она указывает, какая именно работа должна быть выполнена. После запуска она помогает неподготовленным инженерам быстро разобраться во внутреннем устройстве функции и вовлеченных компромиссах.
Конечно, документация полезна только тогда, когда она доступна. В Lyft есть коллекция технических спецификаций, которые любой инженер может просмотреть и к которым может внести свой вклад, организованных в рамках рассылки. Многие инженеры используют ее для получения обратной связи, повышения осведомленности о новых проектах и сотрудничества между командами. Другие используют коллекцию для лучшего понимания существующих функций и сервисов. Ее высокая видимость и прозрачность позволяют даже самым младшим инженерам строить с уверенностью.
Быстрая итерация
Достижение консенсуса по дизайну и реализации функции на стадии технической спецификации означает меньше споров в дальнейшем - это бесценно, когда вы находитесь под давлением, пытаясь запустить функцию. После запуска техническая спецификация служит ценным справочником, где заинтересованные стороны могут быстро найти точную информацию - например, почему были приняты определенные решения по реализации, какова область проекта и как он интегрируется с другими платформами и сервисами.
Прочитав это руководство, вы будете готовы создавать полностью разработанные технические спецификации, которые поднимут ваши функции и команду на новый уровень. Вы поблагодарите нас позже!
Прежде чем вы начнете писать - дайте вашей технической спецификации цель
Принцип Парето - что только 20% ввода обычно приводят к 80% вывода - количественно определяет то, что большинство людей интуитивно понимают: некоторые виды использования времени более эффективны, чем другие. То же правило применимо к написанию технических спецификаций. Рациональное использование вашего времени и усилий принесет вам большие дивиденды позже. Хорошо продуманная техническая спецификация - это инструмент, который работает от вашего имени, облегчая вашу работу и делая вашу функцию лучше. У него есть цель - например, улучшение внутрикомандной коммуникации или прогнозирование и решение проблем заинтересованных сторон. Техническая спецификация без цели? Это пустая трата времени.
Чтобы максимизировать пользу от вашей технической спецификации, определите ее цель, прежде чем начинать писать. Спросите себя: "Чего я хочу достичь с помощью этой технической спецификации?" Принятие этого решения заранее упрощает процесс написания и гарантирует, что спецификация будет полезна для ее читателей (и, следовательно, для вас). Ваш ответ будет основой вашей технической спецификации, определяя такие атрибуты, как технические детали. Эта сетка представляет несколько общих целей для технических спецификаций и то, как эти цели отражаются в окончательной технической спецификации:
По мере изменения вашего проекта и цели, ваша спецификация тоже будет меняться. Ранние стадии проекта могут потребовать высокоуровневой спецификации, предназначенной для получения поддержки заинтересованных сторон. После того, как поддержка получена, вы можете преобразовать вашу спецификацию в документ более низкого уровня, который описывает всю инженерную работу, необходимую для завершения проекта, включая конкретные API, ошибки и аналитику.
Написание технической спецификации - ключевые разделы
Хотя каждая техническая спецификация выглядит по-разному, начиная с шаблона, вы можете использовать известные передовые практики. Здесь мы представим свободный шаблон для технических спецификаций, проходя через спецификацию для гипотетического проекта под названием Spot the Bot - Twitter-бот, который будет твитить милые картинки щенков.
Если это применимо - например, для работы с фронтендом или клиентом - добавьте основной макет или скриншот в верхнюю часть документа, чтобы читатели могли получить интуитивное, визуальное представление о проекте.
Резюме
Это абстрактная часть вашей технической спецификации: кто/что/когда/где/почему вашего всего предложения, сделанного кратким.
Spot the bot - это твиттер-бот, который твитит картинки собак на предопределенных хронологических интервалах. Изображения собак получаются с помощью GET-запроса к Dog API.
Контекст
Контекстуализируйте свой проект: зачем его строить? Какова мотивация? Какие пользовательские проблемы вы пытаетесь решить? Какие предыдущие попытки, если таковые были, были предприняты для решения этой проблемы?
Мы стремимся расширить наш бренд в сегменте миллениалов. Spot the Bot будет ориентирован на аудиторию миллениалов, предоставляя мгновенный доступ к высококачественным, кураторски отобранным картинкам собак. Мы отличимся от конкурентов, предлагая картинки более высокого качества.
Цели
Выделите все результаты, которые, по вашем мнению, должны быть достигнуты в результате успешного выполнения проекта. Это могут быть как качественные, так и количественные цели.
1. Увеличить нашу аудиторию в Twitter на 20% в течение следующих трех месяцев.
2. Получить 500 ретвитов на каждый твит в течение первого месяца.
3. Получить положительные отзывы от пользователей о качестве изображений.
Нефункциональные требования
Нефункциональные требования - это ограничения, которые накладываются на вашу систему или ожидания, которые у вас есть от вашей системы, но которые не относятся к функциональности. Это может включать в себя ожидания относительно производительности, безопасности, доступности, локализации и т.д.
1. Spot the Bot должен быть доступен 99,99% времени.
2. Spot the Bot должен поддерживать минимум 500 запросов в минуту.
3. Spot the Bot должен поддерживать английский, испанский, французский и немецкий языки.
Обзор дизайна
В этом разделе вы должны представить общий обзор того, как будет работать ваша система. Это должно быть высокоуровневым описанием, которое включает в себя все основные компоненты системы и то, как они взаимодействуют друг с другом.
Spot the Bot будет работать на основе сервера, который будет делать GET-запросы к Dog API каждые 30 минут. Каждый запрос вернет изображение собаки, которое затем будет твитнуто на нашем аккаунте в Twitter.
Детали дизайна
В этом разделе вы должны войти в детали о том, как будет работать ваша система. Это должно включать в себя все детали, которые важны для понимания того, как система будет работать, включая, но не ограничиваясь, информацией о том, какие API будут использоваться, какие данные будут храниться, какие алгоритмы будут использоваться, и т.д.
1. Сервер будет написан на Python и будет использовать библиотеку Tweepy для взаимодействия с Twitter API.
2. Сервер будет делать GET-запросы к Dog API с использованием библиотеки requests.
3. Сервер будет запущен на AWS и будет использовать DynamoDB для хранения информации о каждом твите, чтобы избежать повторения изображений.
Тестирование
Опишите, как вы планируете тестировать вашу систему, чтобы убедиться, что она работает правильно. Это должно включать в себя информацию о том, какие типы тестирования вы планируете использовать (например, модульное тестирование, интеграционное тестирование, нагрузочное тестирование), а также о том, какие сценарии вы планируете тестировать.
1. Мы напишем модульные тесты для каждой функции нашего сервера, используя библиотеку unittest.
2. Мы напишем интеграционные тесты, чтобы убедиться, что наш сервер правильно взаимодействует с Twitter API и Dog API.
3. Мы проведем нагрузочное тестирование, чтобы убедиться, что наш сервер может обрабатывать ожидаемую нагрузку.
Развертывание и мониторинг
Опишите, как вы планируете развернуть вашу систему и как вы планируете ее мониторить после развертывания. Это должно включать в себя информацию о том, как вы планируете отслеживать ошибки, как вы планируете отслеживать производительность системы, как вы планируете обновлять систему и т.д.
1. Мы будем использовать AWS CodeDeploy для развертывания нашего сервера.
2. Мы будем использовать AWS CloudWatch для мониторинга ошибок и производительности нашего сервера.
3. Мы будем использовать AWS CodePipeline для автоматического обновления нашего сервера при каждом изменении кода.
Сроки и владелец
Укажите, кто будет владельцем этого проекта и когда он будет завершен. Это поможет управлять ожиданиями и обеспечит ответственность.
Владелец проекта: John Doe
Ожидаемая дата завершения: 1 июня 2023 года
Вывод
Технические спецификации - это мощный инструмент, который может улучшить вашу работу и работу вашей команды. Они могут помочь предотвратить баги, улучшить коммуникацию внутри команды, ускорить итерацию и служить ценной документацией. Но чтобы получить все эти преимущества, вы должны уделить время и усилия на написание хорошей технической спецификации. Надеемся, что это руководство поможет вам в этом процессе. Удачи!
Комментариев нет:
Отправить комментарий