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

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

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

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

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

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

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

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

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

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

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

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

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

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

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