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

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

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

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

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

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

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

📌 Блок покупки
Данные из ответа 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