ИИ-агент
по поиску работы

Собеседование технического писателя: вопросы, ответы и практический кейс

Вопросы техническому писателю и практикум API: исправленный quickstart, справка, OpenAPI и запускаемый пример с проверкой запросов и ответов.

На этой странице

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

Ниже — профессиональные вопросы и авторский кейс об исправлении quickstart API. В приложении есть законченная инструкция, справка, OpenAPI-контракт и исполняемый пример на Node.js. Он работает как локальный диспетчер запросов внутри процесса, без HTTP-сервера и внешнего сервиса. Это учебная задача, а не тест работодателя и не документация реального продукта.

Вопросы и ответы о работе техписателя

«Что показать в портфолио и как рассказать о своей роли?»

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

Подготовь один фрагмент до и после с объяснением решения. Сокращение количества слов само по себе не доказывает пользу: иногда добавленный prerequisite экономит читателю час. Открытое описание роли технического писателя GitLab показывает связь документации с инженерной работой и review. Это пример конкретной роли, а не обещание одинакового отбора во всех компаниях.

«С чего начнёте новую инструкцию?»

«Определю читателя и результат. Разработчик, который впервые подключает API, и оператор, который устраняет инцидент, нуждаются в разных входных данных и деталях. Уточню версию продукта, доступы, исходное состояние и критерий успеха. Затем выполню путь сам или вместе с владельцем предметной области и отмечу точки, где читатель вынужден угадывать».

Google developer documentation style guide помогает выдерживать ясный и последовательный текст для технической аудитории. Но style guide не заменяет постановку: прежде чем выбирать формулировку команды, нужно знать, существует ли она в нужной версии. Если доступ к среде отсутствует, назови, что подтверждено спецификацией и что ещё требует фактического прогона; не ставь отметку «проверено» по внешнему виду примера.

«Чем quickstart отличается от reference?»

«Quickstart проведёт по короткому успешному пути до наблюдаемого результата. Он назовёт необходимые условия, точную команду и ожидаемый ответ. Reference системно опишет параметры, допустимые значения и ошибки. Не превращу первый запуск в полный каталог всех возможностей, но не спрячу обязательную авторизацию в необязательном примечании».

Write the Docs guide предлагает строить документацию вокруг потребностей читателя и поддерживать её вместе с продуктом. В нашем приложении quickstart создаёт одну задачу и читает её. Справка отдельно объясняет формат text, коды ошибок, поведение повторного POST и срок жизни данных. Они связаны, но не повторяют друг друга целиком.

«Как работать с противоречащими источниками?»

«Зафиксирую конкретное расхождение: версия, запрос, ожидаемый и фактический ответ. Сопоставлю утверждённый контракт, реализацию, release notes и подтверждение владельца. Самостоятельно не объявлю случайное поведение багом или новой спецификацией. Если контракт и продукт расходятся, нужно решение ответственного и явная версия, а не маскировка удобной формулировкой».

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

«Достаточно ли сгенерировать документацию из OpenAPI?»

«OpenAPI полезен для структурного контракта операций, request body, response и безопасности. Он не заменяет понятный первый запуск, объяснение жизненного цикла данных и рекомендации по восстановлению после ошибки. Проверю и схему, и выполняемый пример. При этом честно назову уровень проверки: несколько проверенных полей JSON не являются полной валидацией всей спецификации».

Спецификация OpenAPI 3.1.1 задаёт структуру описания API. В архиве есть документ этой версии; тест сверяет ключевые поля и фактические ответы локальной фикстуры. Сторонний полный OpenAPI-валидатор не запускался. Также файл спецификации не означает, что развёрнут HTTP-сервер: наш dispatch моделирует request/response объектами внутри Node.js.

«Как редактировать сложное объяснение, не потеряв точность?»

«Сначала выделю действие, условие и результат. Уберу слова, которые не помогают принять решение, но сохраню ограничения. Термин определю там, где без него нельзя выполнить шаг. Имя параметра и регистр в команде не буду менять ради красивого русского текста. Проверю, что после сокращения не исчезли версия, обязательный заголовок или критерий успеха».

Microsoft Writing Style Guide подчёркивает полезность и ясность текста. В техническом примере это означает конкретное «POST возвращает 201 и id», а не «получите успешный ответ». Вместе с тем не обещай «безошибочную интеграцию»: инструкция помогает выполнить заданный сценарий при перечисленных условиях, а не устраняет все возможные сбои среды.

«Как организуете docs-as-code и review?»

«Хранение Markdown в Git само по себе ещё не задаёт процесс. Уточню владельца материала, связь с релизом, правила проверки примеров и критерии приёмки. Сделаю изменение небольшим и проверяемым: что изменилось в продукте, где обновлён текст и какой прогон подтверждает новый пример. Попросив review, укажу предметные вопросы, а не только просьбу исправить стиль».

Для API-примера полезны автоматические проверки команд и ожидаемых статусов. Они не заменят чтение человеком: тест может подтвердить ответ, но не заметить, что prerequisite спрятан после команды. Если продукт меняется, связанные quickstart, reference и схема должны обновляться согласованно. Архив ниже показывает такую маленькую связку с определённым результатом.

«Как оценить результат документации?»

«Назову наблюдаемое действие: читатель создал задачу и смог её прочитать, оператор нашёл нужный вариант ошибки, новый сотрудник выполнил процедуру. Для количественного вывода нужны определение события, период, выборка и способ сбора. Не буду утверждать, что уменьшил обращения на 30%, если измерения не было».

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

Практикум: исправить первый запуск API

Это авторская задача. Старый quickstart предлагает POST /v0/tasks с application/x-www-form-urlencoded, полем task, без bearer-заголовка и ожидаемым ответом 200. Дано подтверждение владельца: актуальная учебная версия — v1, ниже перечислен её согласованный контракт. Нужно подготовить законченные quickstart, справку и структурное описание, а также проверить пример.

Создание выполняется через POST /v1/tasks. Требуются Authorization: Bearer training-token и точный Content-Type: application/json. Тело — JSON-объект только с text. Text — строка длиной от 1 до 80 Unicode code points; после trim она не должна быть пустой. Сохраняется исходный текст без обрезки пробелов. Успех возвращает 201 и объект с положительным целочисленным id и text.

Чтение GET /v1/tasks/{id} требует того же bearer-заголовка, возвращает 200 и созданный объект. Id в пути записывается положительными десятичными цифрами без ведущих нулей. Нет задачи — 404. Нет правильного токена — 401 до проверки маршрута; неверный тип тела POST — 415; неверная структура — 400. Неподдержанный метод на известном маршруте — 405.

Training-token — публичное значение учебной фикстуры, не действующий секрет. Хранилище находится в памяти одного экземпляра dispatch. Отдельный запуск начинает с пустого состояния, поэтому создание и чтение объединены в client.mjs. Сетевого адреса и удалённого аккаунта нет. Успешный повтор POST создаёт новую задачу: идемпотентность не обещается.

Готовый quickstart и его результат

В готовой инструкции перед командой указано: нужен Node.js с ES modules, файлы client.mjs и fixture.mjs должны лежать рядом, зависимости устанавливать не требуется. Затем читатель переходит в распакованный каталог и запускает node client.mjs. Клиент уже содержит правильные заголовки и JSON с text «Сверить отчёт».

Первый ответ: POST /v1/tasks, status=201, body={"id":1,"text":"Сверить отчёт"}. Второй: GET /v1/tasks/1, status=200 с тем же телом. Обоим соответствует content-type: application/json. Команда действительно выполнена на Node.js 26.8.2; ответ не выдуман для иллюстрации. Полные объекты сохранены в execution-log.json.

Готовый quickstart также объясняет 401, 415 и 400, а не заканчивается единственным «успех». Справка reference.md описывает границы text, форму ошибки {"error":"код"}, повторное создание и сброс памяти после запуска. openapi.json связывает request/response схемы и bearer requirement. Имена файлов в этих ссылках существуют в архиве; будущие материалы читателю не обещаются.

Реплика владельцу продукта после проверки: «Обновил путь на v1, добавил учебный bearer, JSON-поле text и ожидаемый 201. Создание и чтение проверены в локальной фикстуре; справка и схема согласованы с этим примером. Сетевой сервис не проверялся: его в условии нет. Для публикации документации реального API нужно отдельно подтвердить адрес среды и выполнить интеграционный прогон». Это описание результата, а не обращение к пользователю API.

Проверки и ошибки решения

Автоматическая проверка вызывает dispatch и сравнивает успешные статусы и полные тела POST/GET с expected.json. Для 400, 401, 404, 405 и 415 дополнительно сверяются полные тела {error:код} и тип JSON-ответа. Отдельно проверяются 401 без токена, 415 при text/plain, 400 для NULL, массива, отсутствующего text, пустой/пробельной строки, неверного типа и лишнего поля. 80 emoji принимаются, 81 отклоняется: это проверяет Unicode code points, а не длину JavaScript-строки в UTF-16 units.

Проверяются чтение, регистронезависимость имён заголовков, отсутствие записи, путь с ведущим нулём и неподдержанный метод. Ошибочные запросы не расходуют id: первая созданная задача получает 1. Изменение полученного объекта не должно менять хранимый текст; ответ возвращает копию. Эти проверки защищают конкретное поведение фикстуры, не безопасность реального многопользовательского API.

Негативный режим воспроизводит старый запрос без авторизации и получает 401 вместо требуемого успешного создания. Проверка завершается кодом 2. Он не доказывает по отдельности каждую ошибку старой инструкции, поэтому штатные тесты дополнительно проверяют тип тела и другие ветви. Ошибка ожидания «201 вместо старого 200» также сверяется с реально выполненным успешным запросом.

Плохое решение — исправить только стиль, оставить v0 и сказать «ответ будет успешным». Другая ошибка — показать curl к несуществующему серверу либо назвать внутреннюю фикстуру проверкой настоящей интеграции. Здесь ограничение явно включено в quickstart, справку, README и вывод теста.

Файлы для репетиции

Скачай полный практикум техписателя, открой условие и решение с копированием или Markdown. В архиве находятся quickstart.md, reference.md, openapi.json, expected.json, три исполняемых файла .mjs, README и execution-log.json.

Выполни node client.mjs, затем node check.mjs. Для намеренно неверного примера — node check.mjs --negative, ожидаемый код 2. Фактический прогон сделан на Node.js 26.8.2. Проверены исполнение локальных примеров и ключевые поля схемы; HTTP-сокет, внешняя среда, полный OpenAPI-валидатор и пользовательское исследование не запускались.

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