Навыки технического писателя

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

В этой статье речь идет о технических писателях, чьими непосредственными адресатами являются конечные пользователи программных продуктов. Я мало знаю о людях, занимающихся составлением проектной документации, не представляю себе процесс подготовки документов для ФСТЭК или Минцифры, никогда не работал с ГОСТ любых серий, и уже много лет не писал ничего для не технических пользователей.

Hard Skills и Soft Skills

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

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

  graph LR
    A[Технический писатель] --> B[Hard Skills]
    A --> C[Soft Skills]

    B --> D[Работа с текстом]
    B --> E[Владение предметной областью]
    B --> F[Владение инструментами]
    B --> G[Управление знаниями]

    C --> J[Получение информации от экспертов]
    C --> L[Эмпатия к пользователям]
    C --> M[Деловое общение, переговоры
личная эффективность,
обратная связь, планирование]

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

Soft skills я бы перевел как социальные навыки. Эти навыки характеризуют работу в команде и социальное взаимодействие, и позволяют выполнять работу эффективнее.

В этой статье для простоты я оставлю англоязычные термины.

Hard Skills

Hard skills можно изучать, развивать и измерять прогресс во владении. Не обязательно знать их все, достаточно иметь о них представление, чтобы при случае быстро ими овладеть. Я выделяю 4 основные подгруппы:

Работа с текстом

• Грамотное письмо (орфография, пунктуация, синтаксис);
• Владение разными стилями речи и умение выбирать подходящий стиль для задачи;
• Соблюдение стайлгайдов (внутренних и внешних);
• Редактура: проверка логики, структуры, терминологии;
• Адаптация текста под разные аудитории (новички, эксперты, специалисты разных направлений);
• Понимание топологии Diataxis и знание о других типах документов;
• Создание шаблонов типовых документов.

Владение предметной областью

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

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

• Базовое понимание программирования на любом популярном языке. Моя рекомендация — Python, хотя первым языком у меня был JavaScript;
• Работа с API, в первую очередь понимание REST API, реализуемого с помощью протокола HTTP;
• Понимание клиент-серверного взаимодействия, различия бэкенда и фронтенда;
• Понимание работы сети, можно начать с концепций IP-адресов и DNS на базовом уровне и продолжать почти до бесконечности;
• Основы СУБД;
• Знакомство с Linux.

Подробнее эти навыки и знания будут рассмотрены в отдельной статье.

Владение инструментами технического писателя

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

• Docs as Code:
  • Системы контроля версий и связанные платформы — Git, GitHub, GitLab;
  • Генераторы статических сайтов (SSG) — Docusaurus, MkDocs, Sphinx и другие;
  • Языки разметки — Markdown, reStructuredText, AsciiDoc;
  • Генерация документации к API — Swagger / OpenAPI;
  • Прочие инструменты и утилиты, которые помогают работать с исходниками, например Pandoc.
• Платформы для совместного ведения документации:
  • Confluence;
  • Wiki-системы;
  • Инструменты, подобные Notion или Gramax.
• Офисные инструменты:
  • Microsoft Word и Google docs.
• Создание графического контента:
  • Обработка скриншотов — Snagit, GIMP и другие по выбору;
  • Схемы и диаграммы — Mermaid, PlantUML, draw.io, Figma.
• Работа с ИИ-инструментами.
  Сейчас еще сложно выделить какие-то универсальные инструменты, подходящие для всех ситуаций. Типичные задачи — переписывание сложных формулировок, проверка текста и создание черновиков. Выбирайте модель под свои задачи, не забывая о безопасности.

Управление знаниями

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

• Поиск и сбор знаний — выявление "информационных островов" (чаты, коммиты, внутренние-вики);
• Структурирование — создание шаблонов, категорий, меток, унификация представления;
• Актуализация — регулярная проверка и обновление контента в условиях работы с неполной и противоречивой информацией;
• Обеспечение доступности — размещение информации там, где ее можно найти;
• Владение информацией о процессах — понимание того, как устроен процесс разработки и релиза в команде.

Soft Skills

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

Коммуникация с экспертами

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

Пример:
Вместо "Расскажите про API" —
"Какие методы чаще всего используются? В каких случаях возвращается ошибка 403?"

Эмпатия к пользователям

• Понимание контекста использования;
• Предвидение вопросов и ошибок;
• Быть в мире пользователя (по Ильяхову);
• Работать с обратной связью от пользователей в любой доступной форме.

Пример:
Для DevOps: "Передайте токен в заголовок Authorization"
Для бизнес-пользователя: "Где найти токен и как его использовать"

Общие профессиональные навыки

Дополнительные навыки: зона роста

Есть несколько групп навыков, которые были бы полезны как hard skills технического писателя, но относятся к другим специальностям. Можно сказать, что такие навыки обеспечивают рост через T-shaping.

Дизайн и UX

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

• Построение пути пользователя:
  • Как пользователь приходит к решению?
  • Где он теряется? Где ищет помощь?
• Проектирование структуры сайта документации:
  • Логичная структура контента;
  • Правильная навигация;
  • Поиск, фильтры, рекомендации.
• Работа с текстами интерфейса:
  • Правильные тексты для кнопок, ошибок и подсказок;
  • Понятные и унифицированные с документацией формулировки.

Тестирование

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

• Работают ли примеры кода?
• Можно ли выполнить инструкцию шаг за шагом?
• Где пользователь может ошибиться?
• Какие шаги можно упростить?

Аналитика

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

• Веб-аналитика:
  • Google Analytics, Яндекс Метрика;
  • Популярные страницы, время на странице, отказы;
  • Поисковые запросы на сайте с документацией.
• Метрики качества:
  • Количество обращений в поддержку по теме;
  • Частота обновлений страницы;
  • Отзывы пользователей.

• Если страница с высоким трафиком имеет 90% отказов — нужно улучшать структуру.
• Если в поиске часто ищут «ошибка 403» — добавить раздел с рекомендациями по исправлению ошибок.
• Если страница редко обновляется, но много читают — проверить актуальность.

DocOps

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

• Автоматизация проверок:
  • Орфография — с помощью Cspell или Vale;
  • Форматирование — Prettier, Markdownlint;
  • Проверка битых ссылок.
• Интеграция в CI/CD:
  • Сборка документации при каждом коммите;
  • Проверка на наличие ключевых элементов.
• Собственные плагины, скрипты и инструменты, от сниппетов в любимом редакторе до расширений существующих генераторов.