Что нужно для создания документации: инструментарий технического писателя

Как думаете, сколько инструментов нужно освоить, чтобы стать крутым техническим писателем? Многие думают, что достаточно просто освоить текстовые редакторы а-ля Word. Отчасти это так: если вдруг отключатся все компьютеры мира, нам вообще хватит ручки и чистого листа, чтобы продолжать наносить пользу технической документацией. Но пока что (😅) цифровой апокалипсис не наступил, поэтому востребованными на рынке будут те специалисты, которые владеют более широким набором инструментов.

Именно с такими специалистами из числа нынешних и бывших коллег я пообщалась, чтобы поделиться с вами инструментарием технических писателей. Для коллег других специальностей этот набор приоткроет, может, доселе невиданные сферы, которые техписатели (далее – TW) могут охватить помимо создания текстов. А для самих TW ознакомиться с этим списком будет интересно и полезно, чтобы порефлексировать: вот это я тоже умею, а вот тут знаю инструмент получше, а это неплохо бы освоить! Так что присаживайтесь поудобнее и давайте окунемся в почти безграничный мир инструментов технических писателей.

Инструменты «дизайнер»

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

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

Многие используют графические редакторы, схожие с Photoshop, в частности Gimp, когда Paint недостаточно. В нем можно создать эффект затемнения (когда нужно выделить «светом» активную область на скриншоте), более незаметно для пользовательского глаза вырезать лишнюю информацию и т.д. Иногда для документации даже приходится склеивать кусочки разных скриншотов: если фичу надо описать до релиза на проде, на тестовом стейдже нет всех данных c прода, в макетах тоже не все отрисовали, ты садишься и «сшиваешь» воедино кусочки из всех трех источников, чтобы в документации был скриншот «из будущего», то есть как это будет выглядеть после релиза. А иногда приходится и сами макеты трогать, чтобы сделать «правильный» скриншот для документации, так что добавляем к инструментарию Figma, Zeplin и др.

Для создания видеотуториалов и инструкций в гифках некоторые технические писатели используют и стандартные программы захвата экрана, и видеоредакторы (привет, moavi). А иногда подобные инструменты встроены прямо в специализированное ПО для технической документации. Мне, например, доводилось создавать гифки с помощью Help&Manual. Коллеги также советовали инструмент Snagit, который можно использовать как и инструмент для скриншотов и для видеозахвата экрана, так и как графический редактор.

А еще есть пласт инструментов визуализации данных, который чаще встречается в работе аналитиков, но TW он тоже нужен: Visio, Draw.io, Lucidchart и другие аналоги. Конечно, нарисовать простую блок-схему можно в Power Point, но не всегда это удобно и не всегда достаточно «простых» схем. Например, мы у себя в работе используем инструменты с поддержкой PlantUML для построения сиквенс-диаграмм (занимательный факт: Lucidchart не умеет обрабатывать весь синтаксис PlantUML, сейчас мы пользуемся другим инструментом).

Инструменты «разработчик»

Часто техническому писателю (по крайней мере в IT) нужно знать и базовые инструменты работы с кодом. Все благодаря подходу Docs as Code, который подразумевает работу с технической документацией как с кодом. Этот подход используют и внедряют у себя многие компании. Для подтверждения можно пройтись по сайтам поиска работы и посмотреть, в скольких из вакансий TW требуется умение работать с Git или просто упоминание Docs as Code.

Docs as Code можно выстраивать на базе абсолютно разных инструментов, но точно никуда не деться от работы с системами контроля версий: в основном это Git, иногда используют SVN. Так как все-таки TW пишут не код, то глубоко погружаться и использовать какие-то специфичные команды не приходится, хватает стандартного набора: clone, push, pull и т.д., а потолок владения Git у TW это обычно cherry-pick, решение конфликтов и сквош коммитов. Еще часто TW пользуются системами контроля версий через интерфейсные клиенты – Sourcetree, TortoiseGit. Или работают c ветками в веб-версии репозитория или IDE. Да, TW используют в работе и IDE! Среди мною опрошенных специалистов чаще всего использовалась Visual Studio.

А что же такого пишут TW, что под это нужны инструменты разработки? Не ворд-файлы же они там гоняют по веткам? Конечно, нет (но чего скрывать, при незрелом подходе Docs as Code встречалось и такое). В таких инструментах TW обычно работают с:

• документацией в разметке (Markdown, HTML, XML, reStructuredText)

• спецификациями к API (json, yaml)

• файлами ресурсов (если в обязанности TW входит вычитка интерфейсных текстов)

Кстати, для работы со спецификациями API очень полезно и просто использовать Swagger Editor, особенно когда добавляешь новые методы со сложной иерархией вложенных друг в друга схем – редактор и визуализирует внешний вид документа, и стандартно подсвечивает строки с ошибками.

Завершить этот блок хотелось бы старым добрым Notepad++. Это лучший друг TW для задач, выходящих за рамки просто текстовых документов. Да и просто заметки там тоже можно вести, а заметок TW обычно ведут очень-очень много.

Инструменты «писатель»

Многие со стороны думают, что технические писатели все сплошь и рядом мастера Word. Но это скорее миф, потому что в современном мире существуют специализированные системы для создания технической документации. Они обычно включают в себя и возможность импорта в разные форматы (в том числе в специфичный CHM – формат вложенной в десктопные продукты документации), применение технологии единого источника и многое другое. Про них много рассказывать нет смысла – их не так много на рынке, они специфичные и в целом между собой очень даже похожие. Мы же посмотрим на вспомогательные инструменты, с помощью которых TW делают лучше свой текст или упрощают работу с ним.

Как вы догадываетесь, TW печатают очень много текста в течение рабочего дня. Очень-очень много, правда. Поэтому один из наших главных врагов – опечатки, которые закрадываются из-за совсем обидных вещей: не сменил раскладку, торопился зафиксировать мысль, замылился глаз за время работы над текстом. Некоторые программы еще и не поддерживают проверку орфографии, а некоторые поддерживают плохо (например, в Help&Manual мне приходилось загружать по несколько словарей для одного языка, чтобы он начинал подчеркивать красным большинство возможных ошибок).

Плюс, не все символы есть на клавиатуре, приходится их искать где-то в недрах программы или гуглить и копировать. Самый частый пример – дефис, короткое тире и длинное тире. Confluence, например, может проставить длинное тире с клавиатуры: вводишь три дефиса подряд и нажимаешь пробел. А Word не может, но делает из дефиса короткое тире при написании следующего за ним слова. И в каждом инструменте по-разному!

Чтобы хотя бы немного со всем этим бороться, а также чтобы упростить себе работу над текстом, многие TW используют дополнительные утилиты:

• типографскую раскладку Ильи Бирмана для расстановки неразрывных пробелов, символов, отсутствующих на клавиатуре и т.д.,

• Punto Switcher или аналоги для автоматического переключения раскладки (если ты вводишь «ghbdtn», она автоматически превращает это в «привет»),

• LanguageTools для проверки на опечатки,

• textovod.com для проверки на орфографию, пунктуацию и т.д.,

• сервис Главред для очистки текста от словесного мусора.

Но не переживайте, Word мы тоже используем и обычно хорошо знаем 😊

Инструменты «эффективный менеджер»

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

Я эффективный менеджер, outlook – мой главный инструмент…

Как ныне исполняющий обязанности тимлида технических писателей, чувствую всю боль этой фразы, потому что написание этой статьи откладывалось на месяцы именно из-за кучи срочных писем и сообщений😄

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

Заключение

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

Плюс, учитываем, что TW со сменой места работы может кардинально менять сферу и продукты, в которые он погружается. На своем примере скажу, что я освоила работу и в кредитном банковском конвейере, и в сложных b2b продуктах для интеллектуальной обработки данных, и во внутренних сервисах для сотрудников большого высоконагруженного финтеха (причем это далеко не полный список). У каждого TW за спиной минимум несколько таких инструментов, которые они освоили на высоком уровне как пользователи.

Из представленного набора понятно, что обязанности TW выходят далеко за рамки «просто напиши текст». Наши задачи порой требуют сложного технического стека, а порой и творческого подхода. Этим профессия технического писателя и хороша.

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