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

В январе 2024 года мы провели большой социологический опрос среди техписателей и других IT-специалистов, разрабатывающих документацию. В этой серии статей я делюсь результатами нашего опроса.

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

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

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

В январе 2024 года мы провели большой опрос среди техписателей и других IT-специалистов, разрабатывающих документацию. Теперь я начинаю серию статей, в которой поделюсь с вами результатами опроса.

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

Может ли IT-продукт жить без документации?

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

Мировая статистика говорит, что английским владеет примерно 1,4 миллиарда человек, но носителей среди них всего 380 миллионов. То есть статистически семь из десяти читателей англоязычной документации — не носители языка.

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

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

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

(по мнению ChatGPT 4, именно так выглядят технические писатели разных стран и эпох)

Мы (documentat.io) решили подробно изучить рынок труда русскоязычных техписателей.

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

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

Однажды мы в documentat.io решили спасти наших техписов от рутинной ручной замены кавычек и написали для них статью про умную автозамену — с использованием регулярных выражений. Теперь решили поделиться ей на Хабре.

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

Привет, Хабр! Я работаю техническим писателем в компании documentat.io, мы занимаемся заказной разработкой технической документации, в том числе на английском языке.

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

В этой статье разберём другую разновидность подводных камней английского — двусмысленные конструкции. Даже носители языка иногда упускают их из виду. А ведь любое двусмысленное выражение может затруднить понимание текста, особенно для пользователя, который только начинает разбираться в предмете. Каждая запинка при чтении приближает пользователя к тому, чтобы бросить документацию и пойти дёргать техподдержку или писать про продукт гадости в интернете. Таким образом, двусмысленность в конечном счёте может стоить бизнесу денег.

Это первая статья в корпоративном блоге компании documentat.io. Мы занимаемся заказной разработкой технической документации и помогаем компаниям настраивать процессы документирования.

Многие разработчики сталкиваются с тем, что писать и поддерживать документацию трудно: непонятно с чего начать, что и куда написать, и как это безобразие дополнять по мере развития проекта. Часто в результате получается документация, которую тяжело читать. А значит пользователи читать её и не будут, вместо этого будут действовать методом проб и ошибок или дёргать техподдержку. И это в лучшем случае. В худшем — откажутся от использования продукта. В итоге пострадают все: и разработчики, и пользователи, и техподдержка, и бизнес.

Как структурировать документацию так, чтобы писать её стало проще?

Я работаю техническим писателем в компании documentat.io. Мы занимаемся заказной разработкой технической документации, в том числе на английском языке. Иногда я дорабатываю уже существующие документы или спецификации к API на английском. Как правило, такие документы написаны русскоязычными разработчиками, которые неплохо владеют английским. И всё же они часто допускают характерные грамматические, пунктуационные и стилистические ошибки.

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

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