Главная on Portfolio — Technical Writing

Mon, 01 Jan 0001 00:00:00 +0000

Docs as Code

Исходники документации хранятся в Git.
Изменения проходят через Pull Request и code review.
Публикация автоматизирована через GitHub Actions.

Mon, 01 Jan 0001 00:00:00 +0000

Interview Pitch (90 секунд)

Я AI Technical Writer / Product UX Writer с инженерным бэкграундом и 10+ годами в IT.

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

Я работаю на стыке продукта, разработки, дизайна и QA:

уточняю требования и фиксирую решения;
описываю пользовательские сценарии, edge cases и состояния интерфейса;
пишу UX-тексты для ошибок, уведомлений, статусов, кнопок, плейсхолдеров и onboarding;
готовлю пользовательскую и внутреннюю документацию: FAQ, troubleshooting, инструкции, release notes;
помогаю команде заранее увидеть неописанные сценарии и риски.

Отдельно я развиваю применение AI в техническом письме и UX-writing:

Mon, 01 Jan 0001 00:00:00 +0000

ИИ в моей работе

Как я использую ИИ в цикле документации без потери качества и контроля.

Кейс

AI Workflow Case

Применение

Черновики структуры
Вычитка и переформулирование
Проверка консистентности терминов
Генерация вариантов UX-текста

Mon, 01 Jan 0001 00:00:00 +0000

AI Workflow Case

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

Принцип

AI помогает ускорять черновую работу, но финальное решение остается за автором.

Я использую AI для:

структурирования неоформленных материалов;
поиска нестыковок в сценариях;
подготовки вариантов формулировок;
сокращения длинных описаний;
проверки единообразия терминов;
подготовки вопросов к разработке, дизайну или QA.

Я не использую AI как источник истины. Факты проверяются по требованиям, макетам, задачам, API-контрактам и решениям команды.

Mon, 01 Jan 0001 00:00:00 +0000

Кейс: объяснить API простыми словами

Кейс показывает, как я объясняю техническое понятие для пользователя без инженерного бэкграунда.

Задача

Объяснить, что такое API, коротко и без потери смысла. Аудитория — пользователь ПК, который знаком с базовой терминологией, но не работает с разработкой.

Подход

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

Версия объяснения

API — это набор правил, по которым разные приложения обмениваются данными и командами.

Mon, 01 Jan 0001 00:00:00 +0000

Case: Explaining API in Plain English

This case shows how I explain a technical concept to a non-technical audience in English.

Task

Explain what an API is in a short, clear way. The audience is a regular computer user who understands basic digital terms but does not work in software development.

Approach

Keep the definition short.
Avoid unnecessary details about HTTP, JSON, methods, and endpoints.
Use a familiar product scenario.
Keep the explanation accurate: an API is not an app itself, but a set of rules for interaction between systems.

Plain English Version

An API is a set of rules that lets different apps talk to each other and exchange data.

Mon, 01 Jan 0001 00:00:00 +0000

Обзор API

Раздел описывает структуру API-документации: цели, аудиторию, стандарт описания и формат примеров.

Внутри раздела

Mon, 01 Jan 0001 00:00:00 +0000

API Reference

Overview

Текущая версия API в этом кейсе: v2.

Endpoints By Resource

Pet

GET /pet/findByStatus - получить питомцев по статусу;
GET /pet/{petId} - получить питомца по ID.

Store

GET /store/inventory - получить статистику инвентаря.

Поиск и фильтрация

Используйте глобальный поиск MkDocs (поле поиска в шапке/сайдбаре) для быстрого перехода по терминам и endpoint-ам.
В ReDoc используйте встроенный поиск по операциям и параметрам спецификации.

GET /pet/findByStatus

Возвращает массив питомцев по статусу.

Mon, 01 Jan 0001 00:00:00 +0000

BPMN: Процесс оформления заказа

Ниже BPMN-подобная диаграмма процесса от выбора питомца до подтверждения заказа.

!!! note “Цель” Показать сквозной бизнес-процесс и точки контроля.

Mon, 01 Jan 0001 00:00:00 +0000

Дашборд продаж

Ниже пример простого дашборда с динамикой заказов.

Mon, 01 Jan 0001 00:00:00 +0000

Кейс: API Reference для платежного сервиса

Контекст

Нужно было повысить качество API-документации платежного сервиса: сократить время первого успешного запроса и снизить количество ошибок интеграции.

Что сделано

введен сценарный Quick Start;
добавлен интерактивный Swagger UI;
унифицирована структура ошибок и примеров;
добавлен changelog и версия документации.

Интерактивное превью API

Открыть Interactive API

До / После

Результат

Time-to-first-call: 20 -> 5 минут.
Доля ошибок первого запроса: 42% -> 18%.

Связанные материалы

Mon, 01 Jan 0001 00:00:00 +0000

C4: Контекст системы

flowchart LR
U["Пользователь"] --> D["Портал документации"]
D --> API["API сервиса"]
API --> DB["База данных"]
API --> MQ["Очередь событий / Kafka"]
API --> EXT["Внешние интеграции"]

Ключевые взаимодействия

Разработчик использует API для интеграций.
GitHub Actions публикует документацию на GitHub Pages.
Портал документации выступает источником контрактов и примеров.

Mon, 01 Jan 0001 00:00:00 +0000

Sequence: Создание заказа

Поток

Клиент отправляет POST /store/order.
API передает запрос в сервис заказов.
Сервис сохраняет заказ в БД.
Клиент получает 201 Created.

Mon, 01 Jan 0001 00:00:00 +0000

UML Class Model

Основные сущности

Pet
Order
User

Mon, 01 Jan 0001 00:00:00 +0000

Docs as Code Pipeline

Эта страница описывает пример пайплайна доставки документации: от Markdown-файла до опубликованного портала.

Что решает пайплайн

Docs as Code нужен, когда документация должна обновляться вместе с продуктом:

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

Архитектура пайплайна

flowchart LR
A["Markdown / OpenAPI"] --> B["Git branch"]
B --> C["Pull request"]
C --> D["Checks: build, links, OpenAPI"]
D --> E["Review"]
E --> F["Merge"]
F --> G["Static build"]
G --> H["GitHub Pages"]

Минимальный набор проверок

Проверка	Зачем нужна
Build	Документация собирается без ошибок
Link check	Нет битых внутренних ссылок
OpenAPI validation	API-контракт синтаксически корректен
Markdown lint	Единый стиль разметки
Spell / terms check	Меньше терминологических расхождений

Пример GitHub Actions

name: docs

on:
 push:
 branches: [main]
 pull_request:

jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - uses: peaceiris/actions-hugo@v3
 with:
 hugo-version: "0.150.0"
 extended: true
 - name: Build docs
 run: hugo --minify

DocOps-ценность

Такой процесс помогает не просто “написать страницу”, а управлять жизненным циклом документации:

Mon, 01 Jan 0001 00:00:00 +0000

Documentation Workflow

Эта страница показывает, как я вижу рабочий процесс документации в продуктовой команде: от задачи в трекере до публикации и обратной связи.

Цель процесса

Сделать документацию частью разработки, а не отдельной активностью после релиза.

Хороший workflow помогает:

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

Роли

Роль	Что дает в процесс
Product / Analyst	Контекст задачи, бизнес-правила, ограничения
Designer	Макеты, состояния интерфейса, UX-логика
Developer	Технические ограничения, API, edge cases
QA	Проверочные сценарии и регрессионные риски
Technical Writer / DocOps	Структура, текст, workflow, публикация

Поток работы

flowchart LR
A["Задача в трекере"] --> B["Сбор контекста"]
B --> C["Карта сценариев"]
C --> D["Черновик документации"]
D --> E["Review: продукт, dev, QA"]
E --> F["Правки и финальная вычитка"]
F --> G["Публикация"]
G --> H["Обратная связь и обновления"]

Definition of Ready

Документационная задача готова к работе, если есть:

Mon, 01 Jan 0001 00:00:00 +0000

Кейс: UX-текст для дополнительной почты

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

Задача

Пользователь получает письма на почту, привязанную к аккаунту Яндекс.Учебника. Часто это не основной ящик: его завели для регистрации и редко проверяют.

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

Mon, 01 Jan 0001 00:00:00 +0000

Игра: Найди ошибку в документации

Найдите 4 ошибки в примере ниже и нажмите Проверить.

POST /store/order создает новый заказ и всегда возвращает 200 OK.

Поле quantity может быть отрицательным, если заказ отменен заранее.

Для авторизации используйте заголовок X-Token, параметр Authorization не поддерживается.

Пример ответа:

{ "id": "abc", "status": 123, "complete": "yes" }

Подсказка

Ошибки связаны с HTTP-статусом, валидацией данных, авторизацией и типами полей ответа.

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started

Base URL

Все примеры в документации используют:

https://petstore.swagger.io/v2

Формат данных

Контент-тип запросов: application/json
Контент-тип ответов: application/json
Кодировка: UTF-8

Быстрый старт за 3 шага

1. Проверить доступность API

curl -X GET "https://petstore.swagger.io/v2/store/inventory"

Ожидаемый ответ 200 OK:

{
 "available": 123,
 "pending": 42,
 "sold": 87
}

2. Получить питомцев в статусе `available`

curl -X GET "https://petstore.swagger.io/v2/pet/findByStatus?status=available"

Ожидаемый ответ 200 OK с массивом объектов Pet.

Пример на JavaScript (fetch)

const response = await fetch(
 "https://petstore.swagger.io/v2/pet/findByStatus?status=available"
);

if (!response.ok) {
 throw new Error(`HTTP ${response.status}`);
}

const pets = await response.json();
console.log(pets.slice(0, 3));

3. Получить питомца по ID

curl -X GET "https://petstore.swagger.io/v2/pet/1"

Ожидаемый ответ:

Mon, 01 Jan 0001 00:00:00 +0000

Interactive API

Интерактивная версия API-спецификации Swagger Petstore для быстрого тестирования запросов.

Обратная связь

Если в Swagger UI не загружается контракт или есть ошибки в примерах:
Открыть issue по Interactive API

Mon, 01 Jan 0001 00:00:00 +0000

Процессы и методология

Как организован процесс Docs as Code: от запроса до публикации.

Кейсы

Этапы

Сбор требований
Проектирование структуры
Подготовка контента
Техническая валидация
Публикация и обратная связь

Mon, 01 Jan 0001 00:00:00 +0000

Финальный QA Checklist

Перед демонстрацией портфолио проверьте:

Quick Start выполняется без правок команд.
Interactive API открывается и загружает openapi.yaml без 404.
Все внутренние ссылки работают.
Диаграммы (BPMN, C4, UML) отображаются на страницах.
Мобильная версия читаема (меню, код-блоки, таблицы).
Темная и светлая тема переключаются корректно.
Последние изменения отражены в Changelog.
CI workflow зеленый на main.
Версия latest доступна в переключателе версий.

Обратная связь

Если нашли проблему в документации: Создать issue

Mon, 01 Jan 0001 00:00:00 +0000

Кейс: баннер о релизе

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

Публичный разбор этого кейса: «Баннер о релизе — это не release notes».

Задача

Нужно придумать текст для баннера на портале поставщиков.

Вводная: завтра в 9:00 команда выкатывает релиз. В течение пары часов некоторые функции могут работать неправильно или быть недоступны.

Mon, 01 Jan 0001 00:00:00 +0000

Сценарий: Онбординг нового магазина

Контекст

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

BPMN (бизнес)

flowchart LR
A[Запрос на подключение] --> B[Проверка документов]
B --> C[Создание аккаунта магазина]
C --> D[Выдача API-ключей]
D --> E[Импорт каталога]
E --> F[Тестовый заказ]
F --> G[Go-Live]

API (технический контракт)

Операция	Метод и путь	Назначение	Успех	Ошибки
Создать пользователя	`POST /user`	Регистрация администратора магазина	`201`	`400`
Добавить питомца	`POST /pet`	Публикация карточек	`200`	`400`, `422`
Загрузить изображение	`POST /pet/{petId}/uploadImage`	Контент карточки	`200`	`404`

Dev-задачи (что меняем в системе)

Добавить шаблон онбординга с чеклистом выполнения шагов.
Добавить endpoint для массовой загрузки карточек питомцев.
Автоматизировать валидацию медиа и обязательных полей.
Ввести onboarding status machine: invited -> active -> verified.

User guide (действия оператора)

Создать учетную запись магазина и администратора.
Сгенерировать и передать API-ключ.
Загрузить минимум 10 карточек питомцев.
Проверить отображение карточек на витрине.
Выполнить тестовый заказ и подтвердить оплату.

!!! warning “Точка контроля” Не переводите магазин в verified, пока не выполнен тестовый заказ end-to-end.

Mon, 01 Jan 0001 00:00:00 +0000

Сценарий: Проверка интерфейсного состояния

Контекст

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

Карта сценария

flowchart LR
A[Пользователь открывает настройки] --> B[Система загружает текущие параметры]
B --> C[Пользователь меняет значение]
C --> D[Показать несохраненные изменения]
D --> E[Пользователь нажимает Сохранить]
E --> F{Ответ сервера}
F -->|Успех| G[Показать подтверждение]
F -->|Ошибка валидации| H[Подсветить поле и объяснить ошибку]
F -->|Техническая ошибка| I[Показать сообщение и предложить повтор]
G --> J[Обновить состояние интерфейса]
H --> C
I --> E

Что нужно зафиксировать в задаче

Зона	Что описать	Зачем
Состояния	Загрузка, несохраненные изменения, успех, ошибка валидации, техническая ошибка	Чтобы UX-тексты и интерфейс не зависели от догадок
Ограничения	Какие поля обязательны, какие значения недопустимы, что делать при конфликте данных	Чтобы разработка и QA одинаково понимали бизнес-логику
Сообщения	Текст ошибки, подтверждение сохранения, подсказка для повторной попытки	Чтобы пользователь понимал, что произошло и что делать дальше
Проверки	Успешное сохранение, повтор после ошибки, уход со страницы с несохраненными изменениями	Чтобы не потерять edge cases перед релизом

Пример UX-текстов

Состояние	Текст
Успешное сохранение	Изменения сохранены
Ошибка валидации	Проверьте значение в поле и попробуйте еще раз
Техническая ошибка	Не удалось сохранить изменения. Повторите попытку
Уход со страницы	Есть несохраненные изменения. Уйти без сохранения?

Вопросы к команде

Нужно ли автосохранение или пользователь явно нажимает кнопку?
Что происходит, если настройки меняются в другой вкладке?
Нужно ли блокировать кнопку сохранения во время запроса?
Кто видит системные ошибки: пользователь, поддержка, администратор?
Где фиксируем событие для аналитики и логов?

Проверки для QA

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

Связанные разделы

Mon, 01 Jan 0001 00:00:00 +0000

Сценарий: Инцидент — сбой оплаты

Контекст

Во время checkout платежный шлюз возвращает ошибки. Нужно минимизировать потери заказов и быстро восстановить стабильность.

BPMN (бизнес)

flowchart LR
A[Рост ошибок оплаты] --> B[Алерт в мониторинге]
B --> C[Триаж инцидента]
C --> D[Переключение на fallback-эквайер]
D --> E[Проверка успешных транзакций]
E --> F[Коммуникация клиентам]
F --> G[Пост-мортем]

API (технический контракт)

Операция	Метод и путь	Назначение	Успех	Ошибки
Создать заказ	`POST /store/order`	Основная операция checkout	`201`	`400`, `402`, `503`
Получить заказ	`GET /store/order/{orderId}`	Проверить финальный статус	`200`	`404`

Требования к ошибке оплаты:

Mon, 01 Jan 0001 00:00:00 +0000

Сценарий: Возврат / отмена

Контекст

Клиент запрашивает отмену или возврат. Система должна корректно проверить статус заказа, зафиксировать решение и инициировать возврат средств.

BPMN (бизнес)

flowchart LR
A[Клиент обращается в поддержку] --> B[Проверка статуса заказа]
B -->|До отгрузки| C[Отмена заказа]
B -->|После отгрузки| D[Оформление возврата]
C --> E[Инициировать возврат платежа]
D --> E
E --> F[Подтверждение возврата]
F --> G[Обновить статус заказа]
G --> H[Уведомить клиента]

API (технический контракт)

Операция	Метод и путь	Назначение	Успех	Ошибки
Получить заказ	`GET /store/order/{orderId}`	Проверить состояние	`200`	`404`
Обновить заказ	`PUT /store/order`	Выставить `cancelled`/`returned`	`200`	`400`, `409`
Удалить заказ	`DELETE /store/order/{orderId}`	Техническая очистка (по политике)	`200`	`404`

Dev-задачи (что меняем в системе)

Ввести явные статусы cancelled, return_requested, returned.
Запретить отмену после статуса delivery_in_progress без флага супервизора.
Добавить audit trail для всех изменений статуса заказа.
Добавить webhook событие order.refund.completed.

User guide (действия оператора)

Найти заказ по orderId.
Проверить, на каком этапе находится доставка.
Если возможно, выполнить отмену; иначе оформить возврат.
Проверить факт возврата средств.
Зафиксировать комментарий причины обращения.

!!! note “Рекомендация” Используйте единый справочник причин отмены для последующей аналитики.

Mon, 01 Jan 0001 00:00:00 +0000

Кейс: инструкция по скриншотам на macOS

Кейс показывает структуру пользовательской инструкции: от базового сценария к частным вариантам и ограничениям.

Задача

Подготовить руководство для пользователя: как сделать скриншот на компьютере с macOS.

В инструкции важно было показать несколько сценариев:

снимок всего экрана;
снимок окна;
снимок части экрана;
снимок меню;
работа через встроенное приложение Screenshot.

Принцип структуры

Пользователь приходит не за описанием инструмента, а за результатом. Поэтому инструкция строится по задачам:

Сценарий	Команда
Снять весь экран	`Shift + Cmd + 3`
Снять окно	`Shift + Cmd + 4`, затем `Пробел`
Снять часть экрана	`Shift + Cmd + 4`
Открыть панель Screenshot	`Shift + Cmd + 5`

Фрагмент инструкции

Скриншот всего экрана

Нажмите Shift + Cmd + 3.
Найдите файл скриншота на рабочем столе.

Примечание: чтобы скопировать скриншот в буфер обмена, нажмите Shift + Cmd + Control + 3.

Mon, 01 Jan 0001 00:00:00 +0000

Пользовательские руководства

Здесь собраны инструкции для конечных пользователей и операторов.

Содержание

Кейс: инструкция по скриншотам на macOS
Онбординг
Базовые операции
Устранение неполадок

Mon, 01 Jan 0001 00:00:00 +0000

Онбординг

Первый успешный запрос

curl -X GET "https://petstore.swagger.io/v2/pet/findByStatus?status=available"

=== “Успех (200)”

```json
[
{"id": 1, "name": "doggie", "status": "available"}
]
```

=== “Ошибка (400)”

```json
{
"code": 400,
"type": "unknown",
"message": "bad input"
}
```

!!! warning “Частая ошибка” Неверное значение status в query-параметре.

Mon, 01 Jan 0001 00:00:00 +0000

Устранение неполадок

`400 Bad Request`

Причина: невалидные параметры запроса.

Проверка:

curl -i "https://petstore.swagger.io/v2/pet/findByStatus?status=wrong"

`404 Not Found`

Причина: ресурс с таким идентификатором не существует.

Проверка:

curl -i "https://petstore.swagger.io/v2/pet/999999999"

Mon, 01 Jan 0001 00:00:00 +0000

Версии API

Текущая версия

v2 (активная): Swagger Petstore API, описанная в текущей документации.

Поддерживаемые версии в документации

v2 - рабочая версия (текущая).
v3 - шаблон для следующей версии (пока в разработке).

Политика версионирования

Новая major-версия получает отдельный раздел документации.
Для каждой версии фиксируются поддерживаемые endpoints и отличия от предыдущей.
При релизе новой версии changelog должен содержать миграционные заметки.

Шаблон раздела для новой версии (`v3`)

Base URL

https://petstore.swagger.io/v3

Ключевые изменения

Добавить список новых endpoints.
Отметить breaking changes.
Добавить migration guide v2 -> v3.

00. Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

Roadmap (6 недель)

Неделя	Тема	Артефакт недели
1	C4 (Context + Container)	architecture-overview + 2 диаграммы
2	BPMN	процесс отклика на вакансию
3	UML Sequence	happy path + error path
4	API docs	3-5 endpoint’ов + ошибки
5	Data + Kafka	ERD + event card
6	Runbook + Diataxis	runbook + release note + упаковка

Система баллов (100)

Точность и корректность: 30
Полнота сценариев и ошибок: 25
Структура документации: 20
Ясность языка: 15
Поддерживаемость: 10

Changelog

Mon, 01 Jan 0001 00:00:00 +0000

Changelog

Все значимые изменения в документации фиксируются на этой странице.

2026-04-30

Added

Добавлен полноценный раздел UX-портфолио под резюме UX Writer / Product Writer.
Добавлены UX-кейсы: онбординг нового пользователя, аудит формы и чеклист UX-текста.
Главная страница обновлена под двойное позиционирование: Technical Writer / DocOps / UX Writer.

Changed

Раздел UX-писательство переработан в витрину UX-кейсов с описанием процесса работы.
Страница Обо мне и контакты обновлена под две версии профиля: technical documentation и UX writing.

2026-04-29

Changed

В контактном блоке ссылка на закрытое резюме на HH заменена на публичный профиль LinkedIn.
Внутренние ссылки обновлены под текущий адрес сайта: /portfolio/.
Ссылка на GitHub-репозиторий обновлена после переименования проекта в portfolio.

2026-04-28

Added

Для страницы Changelog добавлен front matter с ShowToc: false, чтобы убрать шумный TOC в боковой панели.

Changed

Обновлена палитра портала: базовый фон сменен на #1c1e20 для более мягкого тёмного тона.
Главная страница адаптирована под Hugo/PaperMod: заменен MkDocs-синтаксис кнопок на HTML-кнопки (cta-btn), исправлены ссылки карточек.
Переписаны кастомные стили под PaperMod, убраны конфликтующие правила .md-* от MkDocs.
Для контейнера .main снято принудительное растягивание (min-height), чтобы не создавать пустое пространство на коротких страницах.

Fixed

Исправлена читаемость Interactive API: повышен контраст текста и элементов в Swagger UI на тёмной теме.
Дополнительно исправлена читаемость блока Schemas (модели, свойства, скобки и разделители).
Убран фон у pre-блоков (.post-content pre) для более чистого отображения кода.

2026-04-19

Added

Добавлена страница Interactive API со Swagger UI на базе openapi/openapi.yaml.
Миграция портала на тему Material for MkDocs.
Добавлены разделы портала: Бизнес-аналитика, Разработчикам, Пользователям, О проекте.
Добавлены страницы с контентом: BPMN, C4, UML, onboarding, troubleshooting, дашборд продаж.
Добавлены исходники диаграмм PlantUML (docs/diagrams/*.puml) и скрипт рендера scripts/render-diagrams.sh.
Добавлена страница Docs as Code с описанием подхода.

Changed

Репозиторий и сайт переведены на новое имя: petstore-api-docs (обновлен site_url).
Усилен Quick Start: добавлен пример на JavaScript (fetch) и блок проверки типовых ошибок (400, 404).
Обновлена навигация портала с многоуровневой структурой.
CI workflow обновлен: установка зависимостей из requirements.txt, рендер PlantUML-диаграмм и сборка портала перед деплоем.
Добавлены критерии качества и измеримые показатели на главной странице.
Добавлены разделы обратной связи на ключевые страницы портала.
Добавлен README.md для быстрого ревью кейса рекрутером/лидом.
Добавлен финальный QA Checklist в документацию.
В CI добавлена валидация OpenAPI спецификации перед рендером и деплоем.
Улучшен UX портала: обновлены тема/палитра, вкладки навигации, breadcrumbs и интегрированный TOC.
Главная страница переработана в формат карточек разделов для быстрого сканирования.
Удалены страницы-заглушки из структуры документации.

Fixed

Локализация пагинации (Previous/Next) стабилизирована с учетом динамической перерисовки темы.
Исправлен CSS-отступ заголовков (margin-bottom: 10px) через docs/stylesheets/extra.css.
Исправлена загрузка OpenAPI в Interactive API (fallback путей, устранен 404).
Исправлены несовместимые диаграммы xychart-beta в сценариях (замена на совместимый формат).

QA

Release check passed: проверены ключевые страницы latest/ и root (/), включая Interactive API, сценарии, версии и changelog.

2026-04-11

Added

Добавлен раздел Changelog в структуру документации.
Добавлена страница истории изменений для портфолио-кейса.
Добавлена страница Версии API с политикой версионирования и шаблоном для v3.
Добавлен плагин поиска search в конфигурацию MkDocs.
Добавлен кастомный CSS docs/stylesheets/extra.css для управления отступами заголовков.

Changed

Обновлена структура API Reference: endpoints сгруппированы по ресурсам (Pet, Store).
В API Reference добавлен раздел про поиск и фильтрацию в документации.
В Getting Started исправлена разметка списков для корректного отображения по строкам.

Fixed

Исправлена локализация пагинации (Previous/Next) в теме Read the Docs.
Улучшен JS-хук локализации, чтобы перевод применялся после динамической перерисовки DOM.
Удалены лишние блоки с общими best practices с главной страницы.

2026-04-10

Changed

Проект переведен с плейсхолдерного TaskFlow API на публичный Swagger Petstore API.
Обновлены Home, Getting Started, API Reference и openapi/openapi.yaml под реальные публичные эндпоинты.

Added

Добавлены русские подписи пунктов меню в навигации документации.

2026-04-09

Added

Подготовлена базовая структура контента для API-документации: Home, Getting Started, API Reference.
Добавлены примеры запросов и ответы для быстрого старта.

Fixed

Исправлен CI-деплой GitHub Pages: добавлено разрешение contents: write в workflow.

Exams

Mon, 01 Jan 0001 00:00:00 +0000

Exams

Midterm (после Week 3)

Теория: 10 вопросов
Практика: 1 sequence + 1 C4

Final (после Week 6)

Теория: 20 вопросов
Практика: C4 + BPMN + API + Event + Runbook

Knowledge Base

Mon, 01 Jan 0001 00:00:00 +0000

База знаний проекта

Цель

Сделать знания о продукте доступными для команды без устных пересказов и потери контекста.

Что входит в базу знаний

Архитектура: контекст системы, сервисы, зависимости.
API и контракты: endpoint’ы, ошибки, ограничения.
Пользовательские сценарии: happy path и edge cases.
Инциденты: runbook, troubleshooting, postmortem.
Релизы: release notes и изменения по версиям.

Структура

Product Overview
Architecture
API
Integrations
User Flows
Operations (runbooks)
Release Notes
FAQ

Процесс актуализации

Любое изменение функциональности должно иметь doc-обновление в том же цикле.
Изменения в документации проходят review вместе с задачей разработки.
Для критичных разделов назначены владельцы (owner + backup).
Раз в спринт проводится ревизия устаревших страниц.

Definition of Done для документации

Изменение считается завершенным, если:

Progress Log

Mon, 01 Jan 0001 00:00:00 +0000

Progress Log

Неделя	Что сделано	Балл	Комментарий
1
2
3
4
5
6

Quizzes

Mon, 01 Jan 0001 00:00:00 +0000

Quizzes

Каждую неделю

5-10 вопросов по теме недели.
Минимум 80% правильных для перехода.

Раз в 2 недели

Смешанный квиз по пройденному материалу.

Release Notes

Mon, 01 Jan 0001 00:00:00 +0000

Release Notes

Пример 1: Релиз профиля пользователя (v2.14.0)

Дата: 2026-05-01 Статус: Production

Что изменилось

Добавили подтверждение смены email через код.
Улучшили сообщения об ошибках при вводе кода.
Добавили логирование причин неуспешной верификации.

Для пользователей

Процесс смены почты стал понятнее: система сообщает, почему код не принят.
При повторной отправке кода отображается ограничение по таймеру.

Для поддержки

Новые коды ошибок: EMAIL_CODE_EXPIRED, EMAIL_CODE_INVALID, EMAIL_RATE_LIMIT.
В тикетах запрашивать requestId для диагностики.

Для команды

API: POST /api/v1/profile/email/confirm.
Логи в Kibana: profile-email-confirm.
Метрики: email_confirm_success, email_confirm_failed.

Риски и откат

Риск: рост ошибок при старых клиентах.
Откат: feature flag email_confirm_v2 в значение off.

Пример 2: Релиз уведомлений о занятиях (v2.15.0)

Дата: 2026-05-08 Статус: Production

Tech Writing

Mon, 01 Jan 0001 00:00:00 +0000

Что я делаю в роли Technical Writer

Описываю функциональность ИТ-продукта с точки зрения пользовательских сценариев и технической реализации.
Создаю и поддерживаю в актуальном состоянии базу знаний проекта.
Пишу release notes для команды проекта.
Читаю и создаю техническую документацию: API, инструкции, регламенты.
Уточняю детали работы функциональности в связке с разработкой, QA, аналитикой и дизайном.

Кейсы

Кейс	Что внутри
Архитектура и диаграммы	C4/sequence, зависимости, контекст
Документация API	endpoint’ы, примеры, ошибки
Сценарий: создание заказа	сквозной flow UI → API → backend
Инцидент: сбой оплаты	диагностика, шаги восстановления
Release Notes	формат релизных заметок: для пользователей, поддержки и команды
Knowledge Base	структура базы знаний и процесс актуализации
Docs as Code pipeline	процесс обновления и review документации

Контакты и CV

Резюме и контакты

UX Writing

Mon, 01 Jan 0001 00:00:00 +0000

Кейсы

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

Кейс	Что внутри
Дополнительная почта	пересмотр тестового: как отделить служебные письма от маркетинговой рассылки
Релизный баннер	пересмотр тестового: как предупредить о релизе и не смешать это с рассказом о новых функциях
UX-аудит формы	улучшение полей, подсказок и валидации

Контакты и CV

Резюме и контакты

UX-кейс: аудит формы

Mon, 01 Jan 0001 00:00:00 +0000

UX-кейс: аудит формы

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

Контекст

Форма собирает контактные данные пользователя. Команда хочет снизить количество ошибок и незавершенных отправок.

До

Email
Введите корректное значение.

Телефон
Неверный формат.

Комментарий
Заполните поле.

Проблемы

Элемент	Проблема	Риск
Email	Не объяснено, зачем нужен адрес	Пользователь может указать нерабочую почту
Телефон	Ошибка не показывает формат	Пользователь повторяет ошибку
Комментарий	Неясно, что писать	Поле заполняют случайным текстом
Общая логика	Все ошибки звучат одинаково	Интерфейс не помогает исправиться

После

Рабочая почта
На этот адрес отправим подтверждение и уведомления по заявке.

Телефон
Введите номер в формате +7 900 000-00-00.

Комментарий
Опишите задачу в 1-2 предложениях. Например: "Нужно подключить новый филиал к отчетам".

Ошибки после редактуры

Не удалось отправить форму
Проверьте обязательные поля и попробуйте еще раз.

Укажите рабочую почту
Мы отправим туда подтверждение заявки.

Введите телефон в формате +7 900 000-00-00
Так менеджер сможет связаться с вами без уточнений.

Что изменилось

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

Чеклист проверки формы

У каждого обязательного поля понятна причина обязательности.
Ошибка показывает ожидаемый формат или следующий шаг.
CTA описывает действие: Отправить заявку, а не ОК.
Текст короткий и помещается в интерфейс.
Термины совпадают с help center и письмами.

Week 1: C4

Mon, 01 Jan 0001 00:00:00 +0000

Week 1: C4 (Context + Container)

Конспект

C4 нужен, чтобы показать систему сверху вниз: кто взаимодействует с продуктом, какие контейнеры участвуют и где границы ответственности.

Практика

Обязательное: C4 Context + C4 Container для кейса “Отклик на вакансию”.
Optional: добавить 5 открытых вопросов к архитектору.

Чеклист

Понятно, кто внешние акторы.
Понятно, где frontend/backend/database.
Понятно, какие внешние интеграции.
Есть легенда/глоссарий терминов.

Мини-квиз (5)

Чем Context отличается от Container?
Какие границы системы обязательно показывать?
Что не стоит добавлять в Context-диаграмму?
Как связать C4 с API-документацией?
Какие ошибки при построении C4 самые частые?

Артефакт недели

Ссылка на файл: ...

Week 2: BPMN

Mon, 01 Jan 0001 00:00:00 +0000

Week 2: BPMN

Конспект

BPMN показывает бизнес-процесс: роли, этапы, развилки, исключения. Это не техническая последовательность вызовов.

Практика

Обязательное: BPMN “Отклик -> Скрининг -> Решение”.
Optional: добавить SLA-метки на ключевые этапы.

Чеклист

Определены роли.
Есть точки принятия решения.
Есть путь отклонения/ошибки.
Процесс понятен без разработчика.

Мини-квиз (5)

Чем BPMN отличается от Sequence?
Какие роли обязательны в этом процессе?
Где показать ручной шаг рекрутера?
Как обозначить исключение?
Что считать завершением процесса?

Артефакт недели

Ссылка на файл: ...

Week 3: Sequence

Mon, 01 Jan 0001 00:00:00 +0000

Week 3: Sequence

Практика

Обязательное: Sequence для “Отклика” (happy path).
Обязательное: Sequence для ошибки (duplicate, timeout или validation).

Мини-квиз

Чем sync и async вызовы отличаются в диаграмме?
Где отмечать retries?
Что такое критичный путь сценария?
Какие ошибки нужно показывать в sequence?
Когда sequence не нужен?

Week 4: API

Mon, 01 Jan 0001 00:00:00 +0000

Week 4: API

Практика

Обязательное: описать POST /applications, GET /applications/{id}, GET /vacancies.
Обязательное: добавить ошибки 400/404/409/422 и что делать клиенту.

Мини-квиз

Что обязательно в API reference?
Чем 409 отличается от 422?
Где описывать rate limit?
Какие примеры нужны в response?
Что такое idempotency и где его фиксировать?

Week 5: Data + Kafka

Mon, 01 Jan 0001 00:00:00 +0000

Week 5: Data + Kafka

Практика

Обязательное: ERD для candidate/vacancy/application/resume.
Обязательное: карточка события application.created.

Мини-квиз

Что должно быть в event contract?
Зачем нужен DLQ?
Что такое source of truth?
Как связать API поле с БД?
Что проверить при дублях событий?

Week 6: Runbook + Diataxis

Mon, 01 Jan 0001 00:00:00 +0000

Week 6: Runbook + Diataxis

Практика

Обязательное: Runbook для инцидента “не уходят уведомления”.
Обязательное: 1 release note с user+tech блоком.
Обязательное: разложить материалы по Diataxis.

Мини-квиз

Чем How-to отличается от Reference?
Что обязательно в runbook?
Какие метрики указывать в troubleshooting?
Что входит в релизный блок для поддержки?
Когда документация считается готовой?

Архитектура и диаграммы

Mon, 01 Jan 0001 00:00:00 +0000

Раздел с архитектурными артефактами: C4, UML, последовательности, потоки данных и бизнес-процессы.

Задача этого раздела: быстро объяснить, как устроена система, где проходят границы ответственности и как функциональность работает в реальных сценариях.

Типы артефактов

Контекстная диаграмма
Диаграмма компонентов
Диаграмма последовательности
BPMN-процесс
ERD / модель данных

Что документирую в архитектуре

Границы системы: что внутри продукта, что относится к внешним интеграциям.
Основные сервисы и их ответственность: frontend, backend, API, хранилища, очереди.
Ключевые пользовательские и системные сценарии: happy path и ошибки.
Технические ограничения: зависимости, retry, таймауты, точки отказа.
Связь диаграмм с документацией API, инструкциями и release notes.

Примеры в портфолио

Какие вопросы закрывает раздел

Какие компоненты участвуют в реализации фичи?
Где источник истины по данным?
Какие сервисы вызываются синхронно, какие асинхронно?
Что происходит при ошибках и как система восстанавливается?
Как изменение в одном сервисе повлияет на другие части системы?

Как поддерживаю актуальность

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

Definition of Done для архитектурной документации

Диаграмма отражает текущую реализацию, а не черновую гипотезу.
Для ключевого сценария есть последовательность шагов и обработка ошибок.
Указаны внешние зависимости и зона ответственности сервисов.
Есть ссылки на связанные API-страницы, инструкции и релизные изменения.

Обо мне и контакты

Mon, 01 Jan 0001 00:00:00 +0000

Обо мне и контакты

Я работаю на стыке технической документации, UX writing и документационных процессов.

У меня frontend-бэкграунд и 10+ лет в продуктовой IT-разработке. Это помогает быстро разбираться в логике продукта, ограничениях разработки, API, пользовательских сценариях и интерфейсных состояниях.

Позиционирование

Направление	Что делаю
Technical Writer / DocOps	Навожу порядок в документации, описываю API, сценарии, edge cases, release notes, help center и документационный workflow
UX Writer / Product Writer	Пишу и улучшаю интерфейсные тексты: ошибки, уведомления, onboarding, empty states, email, push и SMS
AI-assisted documentation	Использую AI для структурирования вводных, генерации вариантов, поиска нестыковок и проверки полноты сценариев

Что мне интересно

Небольшие и средние продуктовые команды.
Документация рядом с разработкой: Markdown, Git, OpenAPI, docs-as-code, базы знаний.
UX-тексты, которые помогают пользователю пройти сценарий без тупиков.
Документационные процессы: актуальность, структура, навигация, release notes, workflow.

Контакты

Резюме Technical Writer / DocOps

Mon, 01 Jan 0001 00:00:00 +0000

Резюме Technical Writer / DocOps

Профиль

Technical Writer / DocOps с frontend-бэкграундом и 10+ годами в продуктовой IT-разработке.

Навожу порядок в продуктовой документации: описываю API, пользовательские сценарии, edge cases, release notes, внутренние гайды, базы знаний и документационные процессы.

Понимаю код, REST API, JSON, CI/CD и ограничения разработки, поэтому быстро нахожу общий язык с разработчиками. Работаю с Markdown, Git, OpenAPI/Swagger, Confluence, YouTrack/Jira, Hugo/MkDocs и подходом Docs as Code.

Использую AI-инструменты для структурирования вводных, подготовки черновиков, поиска нестыковок и проверки полноты документации. Факты, термины и продуктовую логику проверяю вручную.

Резюме UX-редактора / Product Writer

Mon, 01 Jan 0001 00:00:00 +0000

Резюме UX-редактора / Product Writer

Профиль

UX Writer / Product Writer с frontend-бэкграундом и 10+ годами в продуктовой IT-разработке.

Пишу и улучшаю интерфейсные тексты: ошибки, уведомления, попапы, empty states, onboarding, подсказки, email, push и SMS. Помогаю командам описывать пользовательские сценарии, находить edge cases и делать продукт понятнее без лишней нагрузки на поддержку.

Работаю с Figma, YouTrack/Jira, требованиями, макетами и техническими ограничениями. Использую AI-инструменты для анализа сценариев, генерации вариантов формулировок и проверки полноты UX-текстов. Финальные решения проверяю вручную по продуктовой логике и пользовательскому контексту.

Резюме и контакты

Mon, 01 Jan 0001 00:00:00 +0000

Резюме и контакты

У меня два смежных, но разных профессиональных фокуса: UX/Product Writing и Technical Writing / DocOps. Для откликов лучше использовать отдельное резюме под конкретную вакансию, чтобы не размывать позиционирование.

Выбрать резюме

Контакты

Email: thankfulfor@ya.ru
Telegram: @fuckinuseless
LinkedIn: linkedin.com/in/narsiya
GitHub: github.com/thankfulfor/portfolio
Портфолио: thankfulfor.github.io/portfolio

Какую ссылку давать

Для вакансий UX-редактора, продуктового редактора, Product Writer, UX Writer и Content Designer лучше давать ссылку на редакторское резюме.

Чеклист UX-текста

Mon, 01 Jan 0001 00:00:00 +0000

Чеклист UX-текста

Короткий чеклист для проверки интерфейсного текста перед передачей в разработку.

Сценарий

Понятно, в каком состоянии находится пользователь.
Текст отвечает на вопрос: что произошло или что нужно сделать дальше.
Нет противоречия между заголовком, описанием и CTA.
Есть безопасный выход: отмена, пропуск, возврат или поддержка.

Ясность

Нет технического жаргона без необходимости.
Один объект называется одинаково во всем сценарии.
Ошибка объясняет, как исправить ситуацию.
Подсказка не дублирует название поля, а добавляет смысл.

Интерфейс

Текст помещается в макет и не ломает верстку.
Вариант для мобильного интерфейса не теряет смысл.
CTA начинается с действия: Создать, Сохранить, Отправить, Открыть.
Empty state помогает начать, а не просто сообщает, что данных нет.

Продуктовая связность

Формулировка согласована с задачей, макетом и техническим ограничением.
Help center, FAQ и release notes используют те же термины.
Если действие необратимо, пользователь предупрежден до подтверждения.
Если есть риск потери данных, он назван явно.

AI-assisted проверка

AI можно использовать для:

Главная on Portfolio — Technical Writing

Docs as Code

Interview Pitch (90 секунд)

ИИ в моей работе

Кейс

Применение

AI Workflow Case

Принцип

Кейс: объяснить API простыми словами

Задача

Подход

Версия объяснения

Case: Explaining API in Plain English

Task

Approach

Plain English Version

Обзор API

Внутри раздела

API Reference

Overview

Endpoints By Resource

Pet

Store

Поиск и фильтрация

GET /pet/findByStatus

BPMN: Процесс оформления заказа

Дашборд продаж

Кейс: API Reference для платежного сервиса

Контекст

Что сделано

Интерактивное превью API

До / После

Результат

Связанные материалы

C4: Контекст системы

Ключевые взаимодействия

Sequence: Создание заказа

Поток

UML Class Model

Основные сущности

Docs as Code Pipeline

Что решает пайплайн

Архитектура пайплайна

Минимальный набор проверок

Пример GitHub Actions

DocOps-ценность

Documentation Workflow

Цель процесса

Роли

Поток работы

Definition of Ready

Кейс: UX-текст для дополнительной почты

Задача

Игра: Найди ошибку в документации

Подсказка

Getting Started

Base URL

Формат данных

Быстрый старт за 3 шага

1. Проверить доступность API

2. Получить питомцев в статусе available

Пример на JavaScript (fetch)

3. Получить питомца по ID

Interactive API

Обратная связь

Процессы и методология

Кейсы

Этапы

Финальный QA Checklist

Обратная связь

Кейс: баннер о релизе

Задача

Сценарий: Онбординг нового магазина

Контекст

BPMN (бизнес)

API (технический контракт)

Dev-задачи (что меняем в системе)

User guide (действия оператора)

Сценарий: Проверка интерфейсного состояния

Контекст

2. Получить питомцев в статусе `available`

`400 Bad Request`

`404 Not Found`

Шаблон раздела для новой версии (`v3`)