Написать данный материал меня побудила статья «Нам он и нафиг не нужон, технический писатель ваш!» (с) или для чего он вам всё-таки нужен» (далее – Статья) и он является отчасти ответом на некоторые мысли, озвученные в ней, а также содержит информацию о моем видении работы технического писателя (далее – ТП). Поэтому также приглашаю автора Статьи @champ_7777777к прочтению.

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

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

Более 10 лет занимаюсь написанием всего и вся, а примеряться к этой деятельности стал намного раньше, еще во время учебы в университете. Львиная доля материалов относится к техническим и около техническим текстам, хотя грань между ними весьма размытая. Степень «техничности» текстов зависит от пожеланий заказчиков и конечно моей погруженности в тематику. Берусь только за задачи, где обладаю компетенциями или могу разобраться и выполнить работу в срок. Последние 5 лет занят в проектировании систем информационной безопасности. В своей работе большую часть времени занимаюсь тем, что собираю информацию, обрабатываю ее и разбираюсь, что написать и меньшую часть непосредственно пишу. Пожалуй, в этом главное отличие профессии ТП от других, связанных с написанием чего-либо – технический писатель – это больше про «технический», чем про «писатель». Это же является и критерием того, как понять, ТП или не ТП:).

Зачем нужен ТП?

В Статье сказано:

Разные компании до сих пор не очень осознают, что это вообще за человек. Многие даже по-разному называют: копирайтер, автор статей, специалист по документообороту.

Компания в целом как раз очень хорошо понимает, для решения каких задач именно им нужен ТП. На разных уровнях по-разному, но понимают.

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

В Статье сказано:

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

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

Основная проблема

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

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

Конечно, можно предложить вариант, что один сотрудник подготовит текст, а другой выполнит оформление. Но человек, занимающийся оформлением и не понимающий того, о чем написано легко может наделать ошибок. Итоговый смысл текста будет совсем не тем, что нужно. Даже если использовать такой подход и отправлять после оформления текст на проверку тому, кто его написал, получается опять же не рационально, а если говорить совсем прямо – дорого. В конечном итоге наиболее оптимальным является вариант, когда человек объясняет и показывает работу устройства ТП, а он разрабатывает документацию.

Тренировать удары

В Статье сказано:

«Однако, тут нужно любить «тренировать 10 тысяч раз один удар, а не 10 тысяч различных ударов», как говорил Брюс Ли. Полировать, оттачивать себя. Тогда придёт профессиональный успех.».

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

Ищу тебя

Здесь скажу про поиск ТП, чего автор Статьи коснулся в разделе «Основная боль».

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

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

Оформление

Из рассмотрено в Статье примера (раздел «Драма и проблематика») коснусь кириллицы в англицизмах.

В Статье сказано:

«Биг дата» — большая натяжка, «жира, гугл почта, иксолла» — совсем не то. Вы спросите, а как понять, как можно, а как нельзя? Честно, я и сам уже многие годы задаюсь вопросом, почему «USB» мы пишем так, а не «ЮСБ», а «СМС» допускается писать кириллицей.

Самый простой способ избежать ошибки – гуглить на предмет используемости.

Можно также использовать Reverso Context или Microsoft Language Portal — здесь можно найти перевод терминов в контексте. Как на русском, так и на английском. Просто можно брать самый употребляемый вариант того или иного термина.

В соответствии с ГОСТ 34.602-2020 техническое задание содержит раздел «Требования к документированию». Хорошим тоном считается указать в нем хотя бы минимальные требования к документации. Они в том числе включают то, что документация разрабатывается на русском языке. Допускается использованием в тексте общепринятых названий технологий, продуктов иностранного производства и т.п. на английском языке. Даже если у вас нет ТЗ по данному ГОСТу или его нет вообще настоятельно рекомендую придерживаться данного правила.

Только «USB» и не смотря на широко распространенное «СМС» – только «SMS». Позволю себе побыть занудой в данном случае. Из Википедии: SMS (сокр. от англ. Short Message Service – «служба коротких сообщений») – технология приёма и передачи коротких текстовых сообщений с помощью сотового телефона. Поэтому «SMS» в технических текстах не должно применяться в качестве синонима этих самых «коротких сообщений» (рука-лицо). Считаю допустимым: «SMS-сообщение». При этом изначально нужно ввести данное понятие, например, так: двухфакторная аутентификация осуществляется посредством ввода имени пользователя и пароля условно постоянного действия с последующим вводом одноразового кода, направляемого пользователю с использованием технологии приема и передачи коротких текстовых сообщений (далее – SMS-сообщения) на телефонный номер, указанный при регистрации. Кроме того, даже не смотря ввод понятия в тексте, оно вносится в список определений. После этого можно смело применять данное определение.

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

Как вам каждый абзац в виде заголовка в 200-страничном документе? И такое бывает. Я не придираюсь и все это вполне допустимо, если человек занимается документами время от времени. Но если вы связали свою профессиональную деятельность с разработкой документов, то изучить основы форматирования просто необходимо. Это не займет много времени. Это также важно, как и само содержание ваших текстов. К тому же значительно упростит жизнь в первую очередь вам.

Заключение

Не затронул некоторые вещи, озвученные в Статье. Одни не связаны с работой ТП или слишком очевидны. Другие потянут на целую статью. Например, вопрос особенностей и перспектив развития ТП – возможно как-нибудь напишу о том, чем я занимаюсь помимо непосредственной разработки документации, как к этому пришел, а также что нужно знать ТП и какие навыки прокачивать, чтобы получить возможность выйти за рамки разработки документации.