С вами Семён Факторович и компания documentat.io. Продолжаю делиться результатами большого техписательского соцопроса, который мы проводили в начале 2024 года.

• О том, кто такие русскоязычные техписатели, где они живут и сколько получают, читайте в первой статье География, демография, зарплаты.

• О том, какую документацию они пишут, в каких отраслях работают, и сколько им платят разные индустрии, читайте во второй статье ГОСТ, индустрии, виды документации, зарплаты.

А в этой части я расскажу о популярных инструментах разработки документации, о форматах её публикации, и о парадигме Docs as Code. И снова про зарплаты, куда без них.

DOCX, HTML или подшитые листы A4? Популярные форматы публикации документации

И на техписательских конференциях, и в техписательских чатах только и разговоров что о Docs as Code, преимуществах разных языков разметки и инструментах публикации в HTML.

Значит ли это, что вся современная документация переехала в веб, и мы можем навсегда забыть о ручной поддержке 600-страничных DOCX-документов в Word?

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

(сумма всех процентных результатов больше 100%, т.к. в вопросе можно было указать несколько ответов)

Интересные выводы:

• Только 39% респондентов публикуют документацию в вебе. Гораздо чаще её отдают читателям в PDF и DOCX (57 и 45% соответственно). Предположу, что причина этому — большой спрос на ГОСТ-документацию, которая традиционно отдаётся в файловых форматах, а не в виде HTML на сайте. Напомню, что по ГОСТам пишут 44% русскоязычных техписателей (см. предыдущую статью о результатах нашего опроса). 

• 18% респондентов печатают свою документацию на листах А4. Скорее всего, это тоже связано с требованиями заказчиков, работающих по ГОСТ. Скорее всего, склонить таких заказчиков к чтению документации в браузере в ближайшее время тоже не получится.

• CHM, стандартный формат справки Windows, бывший популярным вплоть до 2010-х годов, теперь используют только 4% опрошенных техписателей.

Какие инструменты документирования мы используем?

Итак, основная часть документации отдаётся читателям в DOCX и PDF. Неужели несмотря на весь хайп вокруг Docs as Code, главным инструментом техписателя всё ещё остаётся MS Word?

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

(сумма всех процентных результатов больше 100%, т. к. в вопросе можно было указать несколько ответов)

Да, Confluence — самый популярный документационный инструмент среди русскоязычных техписателей. Им пользуется почти две трети (63%) опрошенных.

Нет, Confluence никуда не ушёл. По-видимому, те, кто хотел продолжить пользоваться им в условиях санкций, смогли это сделать.

Нет, Confluence ничем не импортозаместился. В результатах нашего опроса мы не увидели никакой wiki-системы российского производства, имеющей хотя бы 10% популярности Confluence. Возможно, ситуация изменится в ближайшие 2–3 года.

Выводы:

• Confluence — лидер, занимающий 63% рынка используемых инструментов.

• Word используют 61% опрошенных техписателей. Что бы мы ни говорили, это один из самых удобных инструментов для публикации DOCX и PDF (см. предыдущий раздел — наши читатели чаще всего хотят именно эти форматы, а вовсе не молодёжный HTML).

• Инструменты авторинга типа MadCap Flare или Author-IT занимают лишь 6% русскоязычного рынка. Предположу, что в ближайшие годы их доля упадёт ещё сильнее: год от года я наблюдаю, что всё больше компаний мигрируют с этих инструментов на wiki-системы или решения на базе легковесных языков разметки.

• 4% русскоязычных техписателей используют решения на базе DITA. Предположу, что в ближайшие годы эта доля не уменьшится: компании, использующие DITA, делают это годами (а иногда и десятилетиями). С учётом накопленного за это время багажа документации миграция в другие системы будет очень трудозатратной.

А как же Docs as Code?

Внимательные читатели наверняка заметили, что в предыдущем разделе не приводятся никакие результаты, связанные с Docs as Code.

И это неспроста! Дело в том, что я считаю Docs as Code не инструментом, а целой парадигмой разработки документации. Ставить её в один ряд с Google Docs, Confluence и Word нужно с некоторой осторожностью.

Для начала попробуем дать определение этой парадигме.

Docs as Code — набор инструментов, процессов и практик, позволяющих работать с документацией так же, как разработчики работают с программным кодом. Техписатели, использующие Docs as Code:

• Пишут документацию, используя легковесные языки разметки (Markdown, Asciidoc, RST).

• Разделяют контент и его представление: отдают читателям не исходники документации в Markdown/Asciidoc/RST, а собранные из исходников артефакты в выходных форматах: HTML, PDF, DOCX… Для сборки документации при этом используются программные решения, которые в случае публикации в HTML называются SSG (Static Site Generators), а в общем случае — сборщиками.

• Хранят исходники документации в Git или других системах контроля версий.

• Применяют для совместной работы с исходниками типичные для Git процессы (Git workflows): используют фича-ветки (feature branches), мерж-реквесты (merge requests) и т. д.

Определение получилось «сборным», состоящим из нескольких признаков. Вопрос нашей анкеты, касавшийся Docs as Code, тоже пришлось задать в формате «выберите те признаки, которые применимы к вам». И именно поэтому вопрос о Docs as Code не получилось поставить рядом с простыми вопросами вида «Используете ли вы Word? Да/Нет».

Вопрос 16.1. Какие элементы парадигмы Docs as Code используются в вашей команде?

(сумма всех процентных результатов больше 100%, т.к. в вопросе можно было указать несколько ответов)

Интересно, что количество техписателей, использующих Git (38%), оказалось больше, чем использующих легковесные языки разметки (32%). Как так получилось? Может ли техписатель пользоваться Git, но при этом не писать в условном Markdown? Может: в моём опыте довольно много команд использует Git для версионного хранения DOCX-файлов или для синхронизации баз MadCap Flare. Поэтому зафиксируем, что пользоваться Git — не обязательно исповедовать Docs as Code.

С другой стороны, использование Markdown или других языков разметки тоже не обязательно означает применение Docs as Code. Я неоднократно видел команды, использующие Markdown только в качестве разметки для написания статей в вики-систему.

Поэтому мне кажется правильным искать количество приверженцев Docs as Code где-то на пересечении вот этих групп респондентов:

• Используем легковесные языки разметки (32%).

• Храним документацию в Git (38%).

• Имеем сборщик для публикации в HTML/PDF/DOCX и запускаем его вручную (16%) или автоматически (20%), суммарно 36%.

Я бы сделал такую оценку:

А итоговый хит-парад документационного инструментария среди русскоязычных техписателей выглядит вот так:

А что с зарплатами?

В первой статье о результатах нашего опроса я приводил зарплатную статистику рынка труда техписателей в РФ. Среди прочего статистика показала, что медианная зарплата российских техписателей на начало 2024 года — 120 000 ₽ на руки.

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

Перефразируем это в терминах разностей зарплат:

• Техписатели, специализирующиеся на Word, получают на 35 000 ₽ меньше общероссийской медианы (85к против 120к).

• Техписатели, специализирующиеся на Confluence, получают незначительно, на 5 000 ₽, меньше медианы (115к против 120к).

• Техписатели, работающие по Docs as Code, получают на 30 000 ₽ больше медианы (150к против 120к).

Короткие выводы:

• Word — самый невыгодный инструмент для техписателя. Техписатель, специализирующийся только на Word, понижает свою потенциальную зарплату в среднем на 30%.

• Навыки Docs as Code повышают зарплату техписателя в среднем на 25%.

• Использование Confluence держит зарплату техписателя практически рядом с медианой (всего на 4% ниже).

Почему за Docs as Code платят так много?

Разница в медианных зарплатах у Word-техписателей и у техписателей в парадигме Docs as Code получается гигантской: 85 000 и 150 000 рублей соответственно, почти вдвое. Чем обусловлен такой огромный разброс?

Разумеется, Docs as Code требует некоторых специальных навыков (использование Git и SSG, знание языков разметки), а редкие навыки всегда ценятся рынком труда выше. Техписателей, использующих Docs as Code, вдвое меньше, чем пишущих в Word (30% против 61%): как и на любом рынке, меньшее предложение приводит к росту цены.

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

Компании принимают решение о переходе на Docs as Code не потому, что любят хайповые инструменты: бизнесу в целом вообще неважно, пишете ли вы в Word, Confluence, Notion, Obsidian или Emacs. Компании переходят на Docs as Code, когда понимают, что документация имеет самостоятельную бизнес-ценность: приводит новых клиентов, снижает нагрузку на техподдержку, повышает репутацию продукта. А раз документация имеет прямое влияние на бизнес компании, то её нужно развивать и поддерживать с той же гибкостью и скоростью, с какой развиваются основные продукты компании. 

Переход на Docs as Code позволяет настроить для документации те процессы, которые уже давно настроены для кода и продуктовых фич:

• Быстрая выкатка изменений клиентам (CI/CD, автоматическая публикация, публикация нескольких выходных форматов из одного исходника).

• Тесная интеграция с другими продуктовыми процессами (кросс-линковка тикетов разработки и тикетов документационной команды).

• Эффективная совместная работа даже в больших командах (Git, feature branches, ревью через мерж-реквесты).

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

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

• «Мы вручную обновляем 600-страничное руководство пользователя в Word и отправляем его клиентам по почте. Всё работает, клиенты довольны? Отлично, не будем менять процессы! Ничего не поменяли — а зачем тогда платить техписателям больше?»

• «Наша база знаний в Confluence уже 10 лет превосходно отвечает на все вопросы клиентов. Нужно ли нам переходить на Docs as Code? Нет, мы прекрасно решаем наши задачи текущим инструментарием. Но и стимула повышать зарплаты техписателям у нас тоже нет — за 10 лет суть их работы ничуть не изменилась»

Поэтому упоминание Docs as Code в техписательской вакансии — не только «галочка», говорящая об использовании модных инструментов, но и сигнал к тому, что компания видит в документации (и в техписателях!) большую ценность, готова улучшать документационные процессы и развивать свои техписательские команды.

Соответственно, владение Docs as Code не только повышает вашу зарплату, но и открывает вам возможность устраиваться в компании с более высокой культурой документирования и бо́льшим уважением к техписателям.

Подытожим

• Чаще всего русскоязычные техписатели публикуют свою документацию в PDF (57%) и DOCX (45%). Только 39% респондентов используют HTML в качестве формата публикации.

• Безусловный лидер среди документационных инструментов — Confluence. Его используют 63% русскоязычных техписателей.

• Второй по популярности документационный инструмент среди русскоязычных техписателей — Microsoft Word и его аналоги, его используют 61% опрошенных.

• Около 30% русскоязычных техписателей разрабатывают документацию в парадигме Docs as Code.

• Инструменты авторинга типа MadCap Flare используют всего 6% техписателей.

• Техписатели, пишущие только в Word, получают на 30% меньше общероссийской медианы.

• Применение Docs as Code даёт значимый прирост к зарплате: техписатели, работающие в рамках парадигмы Docs as Code, получают на 25% больше общероссийской медианы.

• Владение Docs as Code — не только способ поднять свою зарплату, но и возможность работать в компаниях с более зрелыми документационными процессами.

Что дальше?

Это третья статья из серии материалов о результатах нашего соцопроса. 

В следующей статье я расскажу вот о чём:

• Каков средний размер техписательской команды в российских компаниях.

• Сколько в среднем получает техписатель-тимлид.

• Кто получает больше: техписатель-одиночка или член крупной техписательской команды.

• Где техписатель больше зарабатывает: в большой компании или в маленьком стартапе.

Чтобы не пропустить новые статьи, подпишитесь на наш блог на Хабре и на телеграм-канал documentat.io.