Никто не сделает это за вас! 🫵
Никто не будет учиться за вас.

Если давно задумывались прокачать какой-то навык — вперёд! Новые знания и опыт — это фундамент для роста, а значит и для повышения вашего дохода.

🔹 Хотите поднять уровень своей зарплаты? Учитесь новому и практикуйтесь
🔹 Возьмитесь за статьи, книги и курсы, которые давно откладывали
🔹 Применяйте знания прямо сейчас — делайте учебные проекты, берите новые задачи на работе

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

У вас есть система с пользовательским интерфейсом.
📌 Как описать документацию по системе?

В документации можно описать множество разделов. Сейчас остановимся на описании элементов интерфейса.

Пример: Описание страницы «Акция» в приложении для инвестиций
Для этого разделяем описание веб-страницы на блоки:
- Хедер
- Блок информации об акции
- Блок покупки
- Блок комментариев
- Футер
и т.д.

📌 Блок покупки
Данные из ответа GET /stocks/{stockId}
При выполнении запроса отображается скелетон. Если метод вернул ошибку, то также отображается скелетон.

Описание элементов:

1) Название акции — из stock.name

2) Цена покупки — из price.buy при открытии страницы, затем по вебсокету из buy.price (/stocks/{stockId}/price)

3) Кнопка «Купить» — отображается, если Биржа открыта (это ссылка на логику работы биржи). При нажатии:
1. Если поле Количество не скрыто, происходит Процесс покупки (ссылка на блок покупки)
2. Иначе появляется поле Количество

4) Поле «Количество» — по умолчанию скрыто — инпут — допустимые символы 0-9

📌 Процесс покупки
При нажатии на кнопку «Купить»:
1. Если Количество > 0, вызывается метод POST /stocks/{stockId}/buy с параметрами:
— stockId={stockId из урла}
— quantity=значение в поле Количество
1.1. Если метод вернул http-код=200, то отображается уведомление «Покупка прошла успешно»
1.2. Иначе отображается алерт с ошибкой с текстом из error.textError из POST /stocks/{stockId}/buy
2. ⚠️ Иначе под полем Количество выводится ошибка с текстом «Укажите количество».

#frontend #documentation

Описывайте логику в формате Если — То — Иначе 🧩
Почему?

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

Пример 1: Отображение данных
- Если пользователь авторизован, то отображать приветственное сообщение с именем.
- Иначе отображать кнопку «Войти».

❌ Если бы вы просто написали «Для авторизованных пользователей нужно отображать приветственное сообщение с именем», то у разработчиков остался бы вопрос, так а что делать, если он НЕ авторизован?

Пример 2: Работа с API
Алгоритм обновления данных:
- Если запрос вернул http-код=200, то обновить таблицу данными из ответа.
- Иначе вывести сообщение об ошибке с текстом из error.message.

- Если вернулся пустой массив, то отобразить текст «Данных пока нет».
- Иначе вывести список данных с пагинацией.

Пример 3: Валидация формы
- Если поле «Email» пустое, то отобразить сообщение «Поле обязательно для заполнения».
- Иначе проверить, соответствует ли введённое значение формату email.

Пример 4: Алгоритм авторизации
- Если пользователь авторизован, то открыть страницу профиля.
- Иначе перенаправить на страницу логина.

- Если роль пользователя «Администратор», то отображать панель управления.
- Иначе выводить страницу «Нет прав».

Почему это работает?
📌 Такой подход универсален. Его понимают и фронтендеры, и бэкендеры, и QA-инженеры, и системные аналитики.
📌 Логика становится очевидной даже через несколько месяцев после написания.
📌 Это упрощает тестирование — тестировщики видят все ветки сценариев.

Используйте формат Если — То — Иначе и забудьте про разночтения в ТЗ. 😉

#frontend #documentation

Судя по предыдущему опросу, тема документации актуальна ✍️
Рубрика: взгляд системного аналитика на процессы, кейсы, боли, холиварные темы

Привет! 👋
С вами Вера.
Я тот самый человек, который любит писать документацию.

Мой секрет — я пишу ТЗ сразу в формате доки. Так убиваем двух зайцев — сначала создаём ТЗ, а после релиза оно превращается в документацию.

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

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

💡 Хочу собрать весь накопленный опыт в мини-курс по документации.
🚀 И у вас есть уникальный шанс повлиять на программу!
Напишите, что именно вы хотели бы узнать о документации, ТЗ и др.? Анонимно
https://forms.gle/6wTXhRTmryFjFpS17

Давайте вместе сделаем полезный курс 🔥

#sa_dev #documentation

Плохая задача на фронт? Разбираем на примере 🚨

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

❌ BAD:
* В верхнем левом углу отображается имя пользователя
* Ниже календарная неделя с выделением текущей даты синим. Отображается день недели и число
* Кол-во км пройденных за день
* Кнопка «Details» открывает экран с прогрессом
* Кол-во шагов
и т.д.

Что тут не так?

1️⃣ Задача бесполезна — просто продублировано описание макета.

2️⃣ Указано расположение элементов — это видно на макете, не пишите это в доке.

3️⃣ Нет ясности для разработчика. Что такое Имя пользователя? Откуда брать календарь? Как узнать кол-во км и кол-во шагов?

4️⃣ Нет альтернативных сценариев. А если пользователь был не в сети и км = 0, что показывать? А если сердцебиение слишком высокое?

Как исправить, расскажем в другом посте.

#frontend #documentation

Исправляем задачу на фронт 😎

Перечислить элементы недостаточно.
Как минимум, нужно указать метод, откуда брать данные — из GET /activity/summary.

Но и этого мало.😱
Не всегда можно с ходу понять, какой параметр к чему относится. Фронтендерам часто приходится додумывать, что куда подставить, как что вычислить и с этими вопросами они приходят к нам, системным аналитикам.

Например, в ответе есть параметры distance и dToday.
* distance — это общее расстояние за месяц.
* dToday — как мы предполагаем, это расстояние за день.
Но как разработчику догадаться, что на экране нужно использовать именно dToday, а не distance?

Под параметром dToday может пониматься:
❗ Пройденное расстояние за текущий день
❗ Расстояние, которое осталось пройти сегодня до какой-то цели
❗ Расстояние, которое обновляется реальным временем (например, через трекер)
Без объяснений разработчик может выбрать неверный параметр.

Не будем же скупиться на слова, давайте писать полные постановки 🙌

#frontend #documentation

Альтернативные сценарии

Часто многие продумывают только основной сценарий, а про альтернативные забывают, т.к. «это неважно, потом разберемся».
Не мыслите так ❌

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

Вернёмся к приложению для трекинга активности. Что здесь может пойти не так? 🤔

1️⃣ Пользователь не сделал ни шага
Телефон был выключен? Нет синхронизации? Отображаем: «Нет данных», 0 или что-то другое?

2️⃣ Пользователь неавторизован
Приложение открыто месяцами, пользователь неактивен. Нужно разлогинивать? Показать сообщение: «Вы не авторизованы. Войдите в аккаунт»?

3️⃣ Высокое сердцебиение
Подсветить показатель красным? Вывести уведомление? Включить сигнал?

4️⃣ Нет интернета
Показать старые данные и предложить подключиться к сети?

5️⃣ Заполнить цель активности
Если цель не установлена, отображать: «Установите цель для лучших результатов!»?

#frontend #requirements #documentation

Альтернативные сценарии — самое интересное!
Рубрика: взгляд системного аналитика на процессы, кейсы, боли, холиварные темы

Привет! 👋
С вами Вера.
Я тот человек, который обожает прорабатывать альтернативные сценарии, но признаюсь, иногда слишком увлекаюсь этим процессом! 😅

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

1️⃣ Определяю роли пользователей и их цели
Чего ждут пользователи от системы? Какие функции?

2️⃣ Выделяю приоритетные цели и начинаю их описывать в формате Use Case
* цель — это название юз кейса, а описание цели (юз кейса) состоит из последовательности шагов и других пунктов шаблона.

3️⃣ Затем в виде списка пишу все альтернативные сценарии для выбранных юз кейсов.
Пишу только названия. Детально пока ничего не прорабатываю.

4️⃣ ✍️ Определяю приоритетные альтернативные сценарии с заказчиком и только после этого начинаю их описывать.

Этот метод вдохновлён подходом Алистера Коберна — автора книги «Writing Effective Use Cases». Его структура помогает не утонуть в работе, не забывая о важных деталях.

Попробуйте, это правда упрощает процесс и экономит время! 🙌

#usecase #documentation

Пишите, что обнаружила система

❌ Пользователь забыл пароль и не может авторизоваться — неудачная формулировка.

Мы не знаем, действительно ли пользователь забыл пароль. Возможно:
* Он ошибся в одной букве или символе.
* Забыл переключить раскладку клавиатуры.
* Пароль был введён автоматически, но некорректно.
* 🐈 По клавиатуре прошлась кошка и случайно нажались лишние символы.

Система не способна читать мысли пользователя.

Хорошие формулировки:
1️⃣ Использованы недопустимые символы в логине или пароле
2️⃣ Введённый логин отсутствует в системе
3️⃣ Пароль не соответствует сохранённому в системе
4️⃣ Превышено допустимое количество попыток ввода пароля
5️⃣ Ошибка сервера

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

#usecase #documentation

Идеальная техника для поиска альтернативных кейсов и анализа, что может пойти не так — это Use Case

Use Case описывается по определенному шаблону. Основные пункты — Основной сценарий и Расширения.

Основной сценарий для записи к врачу:
1️⃣ Пользователь выбирает врача.
2️⃣ Система отображает доступные слоты.
3️⃣ Пользователь выбирает дату и время.
4️⃣ Пользователь вводит причину обращения.
5️⃣ Система резервирует слот, врача и кабинет.
6️⃣ Система отправляет уведомление о записи.

Как находить альтернативные сценарии?
Проходим по каждому шагу и задаём себе вопрос: «Что может пойти не так?»

Найденные альтернативы — это расширения основного сценария.

Примеры расширений (альтернативные сценарии):
1️⃣ Пользователь выбирает врача — Что может быть по-другому?
1.а. Врач отсутствует в списке.
Например, пользователь неправильно ввел ФИО врача

2️⃣ Система отображает доступные слоты
2.а. У выбранного врача нет свободных слотов

3️⃣ Пользователь выбирает дату и время
3.а. Выбранный слот был забронирован другим пользователем параллельно.
3.b. Пользователь вводит дату вручную, формат некорректен.

4️⃣ Ввод причины обращения
4.а. Введенное кол-во символов превышает максимально допустимое.

5️⃣ Система резервирует слот
5.а. Врач или кабинет уже заняты в это время.
5.b. Техническая ошибка при резервировании.

6️⃣ Система отправляет уведомление
6.а. Почта пользователя указана неверно.
6.b. Почтовый сервер недоступен.

✏️ Мы проделали ШАГ 1 на пути к проработке сценариев! Мы определили возможные альтернативные кейсы.
Потренируйтесь дальше сами. Попробуйте найти и другие альтернативные сценарии.
✏️ Затем ШАГ 2 — выберите те сценарии, которые действительно будете обрабатывать. А еще подумайте, а как можно спроектировать систему так, чтобы избежать части альтернативных сценариев? 😉
✏️ ШАГ 3 — напишите, как система должна вести себя в случае выполнения этих расширений.

#usecase #documentation

Альтернативные сценарии — не только ошибки!

Судя по опросу, тема юз кейсов актуальна, поэтому продолжим👇

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

Примеры:
1️⃣ Запись к врачу.
Основной сценарий: пользователь выбрал дату, время, указал причину обращения и успешно записался.
Альтернативный сценарий:
✏️ Пользователь выбрал ближайший доступный слот автоматически.
✏️Система предложила врача аналогичного профиля, так как выбранный был занят.

2️⃣ Онлайн-заказ еды.
Основной сценарий: клиент выбрал блюда, оплатил, заказ доставлен.
Альтернативный сценарий:
✏️ Клиент выбрал самовывоз.
✏️ Клиент оплатил заказ при получении.

3️⃣ Регистрация на курс.
Основной сценарий: пользователь заполнил анкету, оплатил, получил доступ к курсу.
Альтернативный сценарий:
✏️ Пользователь воспользовался промокодом.
✏️ Регистрация завершена без оплаты — активирован тестовый доступ.

4️⃣ Текстовое сообщение в телефоне.
Основной сценарий: пользователь набрал текст, система предложила автозамену, пользователь подтвердил замену.
Альтернативный сценарий:
✏️ Пользователь решил оставить свой текст без изменений.
✏️ Пользователь отклонил автозамену, но воспользовался предложением другого слова.

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

#usecase

Про свёртывание ошибок в Use Case

Что мы в основном знаем о технике Use Case? Это последовательность шагов между пользователем и системой. Но без дополнительных знаний и лайфхаков эта техника не раскрывает у писателей весь потенциал.
Одна из полезных техник — свертывание ошибок.

Use case «Обновить программное обеспечение»
Основной сценарий:
1️⃣ Пользователь запускает процесс обновления.
2️⃣ Система проверяет наличие доступных обновлений.
3️⃣ Система устанавливает обновления.
4️⃣ Система проверяет корректность установки.

Обратим внимание на шаг 4. Причин может быть много, почему установка завершилась с ошибкой. В данном юз кейсе пусть нас интересует только одно: обновление закончилось удачей или неудачей?

Пишем расширение:
4а. Установка завершилась с ошибкой.
На этом шаге причины ошибки не важны. Главное, что итог — некорректное обновление.

Но все возможные проверки разработчикам все-равно нужно проработать! Все эти проверки вынесем в отдельный Use Case «Проверить корректность установки». В этом случае каждая ошибка важна.
Основной сценарий:
1️⃣ Система запускает проверку установки.
2️⃣ Система анализирует компоненты.
...

Расширения:
2а. Отсутствуют ключевые компоненты.
2b. Конфликт версий.
2c. Проблемы совместимости с оборудованием.
2d. Ошибки в конфигурации.
...
Здесь ошибки не сворачиваются. Для каждой из них нужно указать конкретное поведение системы: при каких-то кейсах попробовать перезапустить обновление компонента (3 попытки), откатиться на другую версию и пр.

Так когда сворачивать ошибки?
📌 Когда результат Use Case с низкоуровневыми условиями расширений приводит к одному результату в верхнеуровневом Use Case

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

#usecase