как писать требования к веб приложению

Как писать функциональные требования

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

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

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

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

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

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

Функциональные требования: что это такое и зачем они нужны

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

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

Функциональные требования, как правило, состоят из:

User story

User story описывает, что делает пользователь определенной роли для достижения результата, и что нужно сделать разработчику, чтобы воплотить эту задачу в жизнь.

Как правило используется шаблон:

Существуют различные примеры применения этой методологии. Например, так это работает в Trello:

В Retail Rocket мы создаем User Stories в Google Docs, используя таблицы. Это помогает упростить процесс коммуникации между различными командами, поскольку каждый может оставить комментарии и дать фидбек.

Например, так выглядит задача об отслеживании NPS для интернет-магазина:

Благодаря такой визуализации взаимодействия задача пользователя плавно и логично переходит в задачу для разработчиков. Затем наступает очередь use case’ов.

Use cases

Use cases описывает поведение пользователя по шагам при взаимодействии с разрабатываемым продуктом.

Задача пользователя — это то, что делает пользователь для достижения краткосрочных целей.

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

Рассмотрим на примере нашей недавно выпущенной фичи — Галерее изображений и шрифтов для массовых рассылок.

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

Примеры use case’ов:

Почему функциональные требования так важны

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

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

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

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

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

А как вы подходите к постановке задач разработчикам?

Источник

Как разработать веб-приложение за 8 шагов

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

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

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

1. Работа с бизнес-логикой бэкенда

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

2. Выбор языка программирования

Если вам менее важна производительность веб-приложения, пишите на Python (фреймворки Django, Flask), Node JS (фреймворки Express JS, Koa JS, Gatsby JS), Ruby (фреймворки Ruby on Rails, Grape). Если в приоритете скорость приложения — используйте Golang (фреймворки Gingonic, Beego, Revel). Еще вы можете использовать популярный язык программирования от Microsoft — C#, который произносится как «си шарп». Он разработан в качестве языка прикладного уровня для CLR. С# вобрал в себя многое от C++, Модула, Delphi, Smalltalk и Java, но разница состоит в том, что С# исключает модели, которые зарекомендовали себя как проблемные при разработке ПС. К примеру, C# в отличие от C++ не поддерживает множественное наследование классов, но допускает множественную реализацию интерфейсов. Главное, какой бы язык вы не выбрали, кодить на том, который вы хорошо знаете.

3. Реализация бизнес-логики

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

Presenter обрабатывают события от пользовательского интерфейса (UI) и выполняют роль callback из внутренних уровней (Interactors). Presenters легко тестировать и их задача состоит в том, чтобы получить информацию от веб-приложения и преобразовать ее для перемещения presenters на экран с помощью представления (View).

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

4. QA-тестирование бэкенда

Тестирование нужно обязательно делать для того, чтобы знать, правильно ли работает бизнес-логика вашего веб-приложения, а также для того чтобы не проверять постоянно «вручную» работоспособность кода. Используйте автоматическое тестирование для модулей и библиотек, соответствия UI/UX и API. Пропишите несколько вариантов тестирования. Разработайте roadmap для платформы, чтобы управлять испытаниями для всех типов тестирования. Обязательно сделайте подключение инструментов отслеживания текущего покрытия кода, чтобы убедиться в том, что ваше веб-приложение не «виснет» и работает без багов и перебоев.

5. Добавление поддержки сваггера

Swagger – это «умная» документация RESTful web-API. По сути, это фреймворк для спецификации REST API, дающий возможность не только просматривать спецификацию в интерактивном режиме, но и отправлять запросы, именуемые Swagger UI. А теперь на счет веб-приложения.

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

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

6. Работа с бизнес-логикой фронтенда

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

7. QA-тестирование фронтенда

Фронтенд тестируют двумя основными видами тестов — на логику и на отображение. Тесты на логику проверяют логическую реализацию функций и классов. Тесты на отображение отвечают за то, чтобы наполнение демонстрировалось пользователю в том виде, который вы задумали, прописывая фронтенд. Для осуществления QA-тестирования фронтенда используйте такие фреймворки, как Mocha, Chai, Jest, Ava, Enzyme, Jest — они самые ходовые, простые в эксплуатации и наиболее понятные из всех.

8. Мониторинг качества веб-приложения

Когда вы завершили седьмой этап, ваше веб-приложение, можно сказать, готово. Ну, или оно находится на финальной стадии готовности — 98%. Что вам нужно знать по итогу? Естественно, первое, что нужно, — это понять, насколько качественно реализовано приложение, как оно будет работать и на какое время хватит его износостойкости. В этом вам поможет Lighthouse — автоматизированный инструмент с открытым исходным кодом для мониторинга качества вашего веб-приложения. Lighthouse проводит системный аудит производительности и доступности веб-приложения для понимания обычного пользователя.

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

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

Источник

Делаем современное веб-приложение с нуля

Итак, вы решили сделать новый проект. И проект этот — веб-приложение. Сколько времени уйдёт на создание базового прототипа? Насколько это сложно? Что должен уже со старта уметь современный веб-сайт?

В этой статье мы попробуем набросать boilerplate простейшего веб-приложения со следующей архитектурой:

Введение

Перед разработкой, конечно, сперва нужно определиться, что мы разрабатываем! В качестве модельного приложения для этой статьи я решил сделать примитивный wiki-движок. У нас будут карточки, оформленные в Markdown; их можно будет смотреть и (когда-нибудь в будущем) предлагать правки. Всё это мы оформим в виде одностраничного приложения с server-side rendering (что совершенно необходимо для индексации наших будущих терабайт контента).

Давайте чуть подробнее пройдёмся по компонентам, которые нам для этого понадобятся:

Инфраструктура: git

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

Итоговый проект можно посмотреть на Github. Каждой секции статьи соответствует один коммит (я немало ребейзил, чтобы добиться этого!).

Инфраструктура: docker-compose

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

Добавим в репозиторий файл docker-compose.yml следующего содержания:

Давайте разберём вкратце, что тут происходит.

Не менее важный docker/backend/.dockerignore :

Воркер в целом аналогичен бэкенду, только вместо gunicorn у нас обычный запуск питонячьего модуля:

Наконец, фронтенд. Про него на Хабре есть целая отдельная статья, но, судя по развернутой дискуссии на StackOverflow и комментариям в духе «Ребят, уже 2018, нормального решения всё ещё нет?» там всё не так просто. Я остановился на таком варианте докерфайла.

Итак, наш каркас из контейнеров готов и можно наполнять его содержимым!

Бэкенд: каркас на Flask

Теперь наш бэкенд мы можем официально ПОДНЯТЬ!

Фронтенд: каркас на Express

В дальнейшем нам вообще не потребуется Node.js на машине разработчика (хотя мы могли и сейчас извернуться и запустить npm init через Docker, ну да ладно).

В Dockerfile мы упомянули npm run build и npm run start — нужно добавить в package.json соответствующие команды:

Команда build пока ничего не делает, но она нам ещё пригодится.

Добавим в зависимости Express и создадим в index.js простое приложение:

Теперь docker-compose up frontend поднимает наш фронтенд! Более того, на http://localhost:40002 уже должно красоваться классическое “Hello, world”.

Фронтенд: сборка с webpack и React-приложение

Пришло время изобразить в нашем приложении нечто больше, чем plain text. В этой секции мы добавим простейший React-компонент App и настроим сборку.

При программировании на React очень удобно использовать JSX — диалект JavaScript, расширенный синтаксическими конструкциями вида

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

2014 год. apt-cache search java

Итак, простейший React-компонент выглядит очень просто.

Он просто выведет на экран наше приветствие более убедительным кеглем.

Добавим и клиентскую точку входа:

Для сборки всей этой красоты нам потребуются:

webpack — модный молодёжный сборщик для JS (хотя я уже три часа не читал статей по фронтенду, так что насчёт моды не уверен);
babel — компилятор для всевозможных примочек вроде JSX, а заодно поставщик полифиллов на все случаи IE.

Если предыдущая итерация фронтенда у вас всё ещё запущена, вам достаточно сделать

для установки новых зависимостей. Теперь настроим webpack:

Чтобы заработал babel, нужно сконфигурировать frontend/.babelrc :

Наконец, сделаем осмысленной нашу команду npm run build :

Бэкенд: данные в MongoDB

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

В то время, как существуют ORM для MongoDB на питоне, я считаю использование ORM практикой порочной и оставляю изучение соответствующих решений на ваше усмотрение. Вместо этого сделаем простенький класс для карточки и сопутствующий DAO:

(Если вы до сих пор не используете аннотации типов в Python, обязательно гляньте эти статьи!)

Теперь надо создать MongoCardDAO и дать Flask-приложению к нему доступ. Хотя сейчас у нас очень простая иерархия объектов (настройки → клиент pymongo → база данных pymongo → MongoCardDAO ), давайте сразу создадим централизованный царь-компонент, делающий dependency injection (он пригодится нам снова, когда мы будем делать воркер и tools).

Время добавить новый роут в Flask-приложение и наслаждаться видом!

Упс… ох, точно. Нам же нужно добавить контент! Заведём папку tools и сложим в неё скриптик, добавляющий одну тестовую карточку:

Успех! Теперь время поддержать это на фронтенде.

Фронтенд: Redux

Начнём с добавления Redux. Redux — JavaScript-библиотека для хранения состояния. Идея в том, чтобы вместо тысячи неявных состояний, изменяемых вашими компонентами при пользовательских действиях и других интересных событиях, иметь одно централизованное состояние, а любое изменение его производить через централизованный механизм действий. Так, если раньше для навигации мы сперва включали гифку загрузки, потом делали запрос через AJAX и, наконец, в success-коллбеке прописывали обновление нужных частей страницы, то в Redux-парадигме нам предлагается отправить действие “изменить контент на гифку с анимацией”, которое изменит глобальное состояние так, что одна из ваших компонент выкинет прежний контент и поставит анимацию, потом сделать запрос, а в его success-коллбеке отправить ещё одно действие, “изменить контент на подгруженный”. В общем, сейчас мы это сами увидим.

Начнём с установки новых зависимостей в наш контейнер.

Первое — собственно, Redux, второе — специальная библиотека для скрещивания React и Redux (written by mating experts), третье — очень нужная штука, необходимость который неплохо обоснована в её же README, и, наконец, четвёртое — библиотечка, необходимая для работы Redux DevTools Extension.

Начнём с бойлерплейтного Redux-кода: создания редьюсера, который ничего не делает, и инициализации состояния.

Наш клиент немного видоизменяется, морально готовясь к работе с Redux:

Фронтенд: страница карточки

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

Время воспользоваться интеллектом и задизайнить структуру нашего состояния. Материалов на эту тему довольно много, так что предлагаю интеллектом не злоупотреблять и остановится на простом. Например, таком:

Заведём компонент «карточка», принимающий в качестве props содержимое cardData (оно же — фактически содержимое нашей карточки в mongo):

Теперь заведём компонент для всей страницы с карточкой. Он будет ответственен за то, чтобы достать нужные данные из API и передать их в Card. А фетчинг данных мы сделаем React-Redux way.

Для начала создадим файлик frontend/src/redux/actions.js и создадим действие, которые достаёт из API содержимое карточки, если ещё не:

Ох, у нас появилось действие, которое ЧТО-ТО ДЕЛАЕТ! Это надо поддержать в редьюсере:

(Обратите внимание на сверхмодный синтаксис для клонирования объекта с изменением отдельных полей.)

Теперь, когда вся логика унесена в Redux actions, сама компонента CardPage будет выглядеть сравнительно просто:

Добавим простенькую обработку page.type в наш корневой компонент App:

И теперь остался последний момент — надо как-то инициализировать page.type и page.cardSlug в зависимости от URL страницы.

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

Так, секундочку… а где же наш контент? Ох, да мы ведь забыли распарсить Markdown!

Воркер: RQ

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

Есть много опенсорсных реализаций очередей задач; мы возьмём Redis и простенькую библиотечку RQ (Redis Queue), которая передаёт параметры задач в формате pickle и сама организует нам спаунинг процессов для их обработки.

Время добавить редис в зависимости, настройки и вайринг!

Немного бойлерплейтного кода для воркера.

Для самого парсинга подключим библиотечку mistune и напишем простенькую функцию:

Мы объявили свой класс джобы, прокидывающий вайринг в качестве дополнительного kwargs-аргумента во все таски. (Обратите внимание, что он создаёт каждый раз НОВЫЙ вайринг, потому что некоторые клиенты нельзя создавать перед форком, который происходит внутри RQ перед началом обработки задачи.) Чтобы все наши таски не стали зависеть от вайринга — то есть от ВСЕХ наших объектов, — давайте сделаем декоратор, который будет доставать из вайринга только нужное:

Добавляем декоратор к нашей таске и радуемся жизни:

Радуемся жизни? Тьфу, я хотел сказать, запускаем воркер:

Ииии… он ничего не делает! Конечно, ведь мы не ставили ни одной таски!

Давайте перепишем нашу тулзу, которая создаёт тестовую карточку, чтобы она: а) не падала, если карточка уже создана (как в нашем случае); б) ставила таску на парсинг маркдауна.

Пересобрав контейнер с бэкендом, мы наконец можем увидеть контент нашей карточки в браузере:

Фронтенд: навигация

Прежде, чем мы перейдём к SSR, нам нужно сделать всю нашу возню с React хоть сколько-то осмысленной и сделать наше single page application действительно single page. Давайте обновим нашу тулзу, чтобы создавалось две (НЕ ОДНА, А ДВЕ! МАМА, Я ТЕПЕРЬ БИГ ДАТА ДЕВЕЛОПЕР!) карточки, ссылающиеся друг на друга, и потом займёмся навигацией между ними.

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

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

Добавляем глупенький редьюсер под это дело:

Внимательный читатель обратит внимание, что URL страницы не будет изменяться при навигации между карточками — даже на скриншоте мы видим Hello, world-карточку по адресу demo-карточки. Соответственно, навигация вперёд-назад тоже отвалилась. Давайте сразу добавим немного чёрной магии с history, чтобы починить это!

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

А вот как — действие navigate:

Вот теперь история заработает.

Фронтенд: server-side rendering

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

Источник