Подготовка технической документации *

Была у нас тут история, когда легкий перфекционизм помог привести в порядок конструкторскую документацию и регулярно экономить инженерам кучу дней на прохождение бюрократических процедур. В ее основе – создание системы управления расчетными данными и переход от трудночитаемых и трудноинтегрируемых отчетов Mathcad к гибкой связке Jupyter Notebook с Python и Teamcenter. Но основной рассказ будет про то, как преобразовывать и экспортировать математические формулы, таблицы и другие элементы из Jupyter в красивый и удобный вид.

В технической документации часто встречаются фразы с использованием страдательного залога. Параметры там «задаются», файлы «сохраняются», а программа «запускается». Ох, опасная эта форма для строгих и однозначных описаний! Почему же страдательный залог заставляет читателей страдать? Будем разбираться...

Системный аналитик всегда и везде сталкивается с бесконечным количеством диаграмм разного вида, с нотациями (правилами), чтобы нарисовать данные диаграммы и с бесконечным количеством инструментов для их описания. Но мало кто говорит о таком инструменте, как PlantUML. 

Лично мне завесу тайны приоткрыл Альфа-Банк, здесь документация ведется рядом с кодом, и схемы логичнее описывать тоже кодом. Но это не так страшно и не так сложно (почти) как кажется. Давайте я приоткрою ящик Пандоры и сниму кармическое проклятье с  этого инструмента. 

Все мы думаем, что хорошо говорим и пишем на своём родном русском языке. Не зря же в конце концов мы столько учились, да и в деловой переписке у нас всё вроде бы вполне неплохо. Но знаете ли вы о том, что даже для написания IT-документации есть свои правила? Поэтому сегодня в блоге ЛАНИТ на Хабре мы поделимся знаниями о русском «документном» языке. 

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

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

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

Недостаточно просто написать инструкции — важно, как, в каком порядке и где вы их разместите. 

Привет! Это Теодора — технический писатель Платформы, жизненно важного департамента Ozon. Документация для нас имеет большое значение, потому что вся компания пользуется нашими разработками: инфраструктурой as a service; фреймворками и библиотеками; инструментами для работы с базами данных и аналитикой и прочим. Сотни инженеров ежедневно обращаются к нашим сервисам и нуждаются в их описании.

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

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

Вспомним наш любимый мультфильм «Падал прошлогодний снег» с его шикарными крылатыми фразами. Одна из них: «Уж послала, так послала». Вот и система так же — вместо отправки запроса посылает его куда-то далеко. А запросу обидно.

У меня иногда складывается впечатление, что не он служит для нас, а мы служим для этого формата. Поэтому — сэр Markdown.

Пьеса «Технический долг» в 9 частях. Ставится и показывается впервые.