Здравствуйте, в этой статье мы постараемся ответить на вопрос: «Профессия технический писатель». Если у Вас нет времени на чтение или статья не полностью решает Вашу проблему, можете получить онлайн консультацию квалифицированного юриста в форме ниже.
Ответ на вопрос не будет однозначным. С одной стороны, профессиональное образование в этом деле не помешает. Мест, где учиться, достаточно. Самый “официальный” вуз – это, конечно, московский Литературный институт им. А. М. Горького.
Что должен знать и уметь технический писатель?
Требования к техническим писателям:
- Собирать требования к задаче
- Декомпозировать задачи
- Проводить интервью с техническими специалистами
- Передавать работу на вычитку и работать с правками
- Планировать работу над задачей в Trello
- Собирать данные по задаче
- Разрабатывать техническую документацию
- Разрабатывать техническое задание
- Использовать языки разметки Markdown, RST, asciidoc, XML
- Изучать целевую аудиторию продукта
- Работать с чертежами, таблицами, графиками, блок-схемами
Что нужно знать? Инструменты технического писателя
Набор инструментов технического писателя будет отличаться в зависимости от его задач.
- Язык
Высокий уровень английского, если пишете для международного рынка, чёткость изложения, способность писать доходчиво и стилистически правильно. Английский пригодится, даже если писать вы будете на русском, чтобы общаться с коллегами и контролировать качество перевода.
Обращайтесь к руководствам по стилю (о них расскажем чуть ниже), учитесь писать лаконично и понятно для аудитории текста. Например, если текст для новичков, избегайте сложных терминов.
- Копирайтерские навыки
Вам пригодятся навыки определения целевой аудитории и написания текстов с учётом особенностей ЦА, понимание пользы и болей читателя.
Как и для любого текста, нужно уметь собирать и структурировать информацию, писать и оформлять текст так, чтобы его удобно было читать. Так же, как и любой коммерческий текст, техническая документация решает бизнес-задачу. Например, цель руководства пользователя — снизить нагрузку на отдел техподдержки.
- Технические знания
Должностные обязанности технического писателя во многом зависят от того, чем занимается работодатель. К основным обязанностям относятся:
- Разработка технической документации (руководств пользователя и администратора, правил эксплуатации, ТУ, ТЗ, технических паспортов и прочих документов) в соответствии с требованиями ГОСТ и другими стандартами.
- Проверка и корректировка технической документации, поддержание ее в актуальном состоянии.
- Подготовка графических схем по заданным параметрам.
- Анализ новых программных продуктов и их тестирование.
- Сбор информации у всех участников процесса: заказчиков, разработчиков, дизайнеров, тестировщиков и менеджеров.
Также должность технического писателя может включать в себя дополнительные функции:
- Подготовка материалов технических презентаций.
- Обучение работе в новых программных продуктах и поддержка пользователей.
- Участие во внедрении программных продуктов.
- Составление документации на английском языке.
Здесь мы не будем упоминать атавизмы типа «принести чай» и «настроить принтер», а рассмотрим типовые задачи, с которыми работают техписы.
Какими качествами должен обладать
Не важно, собираетесь вы творить только для души или нацелены на заработок. Для работы нужны следующие качества:
- Развитая речь. Написанное скудным языком читать никто не будет.
- Наблюдательность. Видеть невидимое, замечать незамеченное, находить оригинальное в обыденном – без этого не обойтись.
- Развитое воображение. Даже если вы списываете персонажа с лучшего друга, для реализации замысла ему порой нужно придать новые черты и поместить в небывалые обстоятельства. Творцам фэнтези и вовсе без фантазии не прожить.
- Богатый внутренний мир. Часто связан с двумя первыми пунктами. Помогает представлять переживания и чувства героев.
- Настойчивость. Магомет должен не просто идти к горе, а искать все способы подняться на вершину.
- Перфекционизм. Только непрерывное стремление к совершенству поможет стать им. Хотя бы в глазах других.
- Трудолюбие. Без правок создать шедевр почти невозможно.
К данной природой личным качествам необходимо добавить профессиональные:
- Грамотность. Не поспоришь.
- Умение добывать информацию. Порой писатель, как и журналист, общается с десятками людей или исследует не один письменный источник, чтобы сотворить свое произведение. Именно так работал А. С. Пушкин над “Капитанской дочкой”. Сегодня таким образом пишут не только исторические романы, но и многочисленные воспоминания, биографии, различного рода советы (из серии “Как похудеть” или “Как заработать”).
- Организованность. Свое рабочее время планировали Пушкин, Толстой и другие профессиональные писатели. У них не было телевизора и соцсетей, но существовали служебные и семейные обязанности.
- Способность налаживать деловые контакты. Мало быть гением – надо еще и доказать это миру. Рекламировать себя издательствам и читателям, чтобы иметь коммерческий успех (кого коробят эти слова, читайте – “доход”). Не хотите “прогибаться под изменчивый мир” – публикуйтесь на Прозе.ру, в собственном блоге или на сайте. Но в таком случае писательство будет уже не профессией, а хобби.
Плюсы и минусы профессии технического писателя
| Плюсы: | Минусы: |
|
|
Каждый писатель редактирует DITA-файлы у себя в локальной копии, а затем выгружает изменения в SVN. Часто бывает так, что над одним документом работает несколько писателей. Чтобы в этом случае не было конфликта правок, у нас есть специальный чат, где можно оповестить своих коллег о начале работы с определённой частью документа или об обновлении общих коллекций, например — глоссария. Может, это и не самое технологичное решение, но оно работает. Никому из писателей не хочется потом «мёржить» (merge) куски сложных технических текстов.
После обновления локальной копии SVN начинается работа. Мы работаем по задачам в Jira. У нас есть специальный тип задач с префиксом DOC. Обычно они связаны с задачами на разработку или с запросами заказчиков. Задачи на документирование создают менеджеры, которые ведут проект, тестировщики, сотрудники службы поддержки. Заказчик тоже может инициировать изменение документации, задав вопрос, высказав пожелание или жалобу. Team Lead нашей команды планирует деятельность каждого писателя, распределяет задачи, следит за их выполнением и отгрузкой документов.
Какими качествами должен обладать
Не важно, собираетесь вы творить только для души или нацелены на заработок. Для работы нужны следующие качества:
- Развитая речь. Написанное скудным языком читать никто не будет.
- Наблюдательность. Видеть невидимое, замечать незамеченное, находить оригинальное в обыденном – без этого не обойтись.
- Развитое воображение. Даже если вы списываете персонажа с лучшего друга, для реализации замысла ему порой нужно придать новые черты и поместить в небывалые обстоятельства. Творцам фэнтези и вовсе без фантазии не прожить.
- Богатый внутренний мир. Часто связан с двумя первыми пунктами. Помогает представлять переживания и чувства героев.
- Настойчивость. Магомет должен не просто идти к горе, а искать все способы подняться на вершину.
- Перфекционизм. Только непрерывное стремление к совершенству поможет стать им. Хотя бы в глазах других.
- Трудолюбие. Без правок создать шедевр почти невозможно.
К данной природой личным качествам необходимо добавить профессиональные:
- Грамотность. Не поспоришь.
- Умение добывать информацию. Порой писатель, как и журналист, общается с десятками людей или исследует не один письменный источник, чтобы сотворить свое произведение. Именно так работал А. С. Пушкин над “Капитанской дочкой”. Сегодня таким образом пишут не только исторические романы, но и многочисленные воспоминания, биографии, различного рода советы (из серии “Как похудеть” или “Как заработать”).
- Организованность. Свое рабочее время планировали Пушкин, Толстой и другие профессиональные писатели. У них не было телевизора и соцсетей, но существовали служебные и семейные обязанности.
- Способность налаживать деловые контакты. Мало быть гением – надо еще и доказать это миру. Рекламировать себя издательствам и читателям, чтобы иметь коммерческий успех (кого коробят эти слова, читайте – “доход”). Не хотите “прогибаться под изменчивый мир” – публикуйтесь на Прозе.ру, в собственном блоге или на сайте. Но в таком случае писательство будет уже не профессией, а хобби.
Мы пишем документацию в формате DITA. Это формат, основанный на XML, который позволяет сохранять исходный текст документов в структурированном виде. Мы пишем исходники документации в этом формате, для этого у нас есть редактор oXygen XML Author. Затем из этих исходников мы можем собрать итоговый документ в любом нужном формате. Для этого есть специальный Toolkit, содержащий XSLT-преобразования. Наш Toolkit позволяет собирать документы во множестве форматов. Самый востребованный — это PDF, иногда собираем CHM или HTML. При желании мы можем собрать даже EPUB, если заказчик вдруг захочет почитать нашу документацию перед сном на электронной книге. По необходимости мы вносим правки в XSLT-преобразования, чтобы изменить правила сборки документов и их внешний вид.
Чем важна и уникальна профессия
Заметим, что документация, с которой работает данный специалист, может предназначаться для внутреннего или внешнего использования.
Составляя «внутренние» технические документы, их автор обеспечивает оперативный обмен информацией между всеми звеньями производственной цепочки. Задача технического писателя – добиться того, чтобы все сотрудники, задействованные в процессе выпуска продукции, имели единое понимание относительно:
- характеристик отдельных деталей;
- правил эксплуатации приборов, аппаратных комплексов, инструментов;
- порядка применения программного обеспечения;
- методик испытания продукта.
«Внешнюю» документацию технический писатель составляет для клиентов, заказчиков, инвесторов и других заинтересованных лиц «со стороны». В презентациях, рекламных брошюрах, на фирменном сайте компании данный эксперт должен представить сложную для понимания техническую информацию в легкой для восприятия форме.
Написание руководств и инструкций – основная часть работы. А какие руководства бывают?
— Руководство пользователя
– руководство для рядовых пользователей. Описывается всё просто и понятно. Главное – функциональность, описания настроек может не быть.
— Руководство администратора
– документ для тех, кто ковыряется на уровне администратора в крупных комплексах. Пишется только для крупных систем, требующих специалиста, который будет контролировать их.
— Руководство разработчика
– это описание кода, баз данных, элементной базы и физических принципов. Делается для обучения новых сотрудников, чтобы организовать преемственность в коллективе и устранить проблему незаменимости, когда от конкретного специалиста зависит, по сути, вся компания, так как полностью разобраться в коде без него будет практически невозможно.
Внутренняя «кухня» — источники вдохновения
Начиная работать над очередной задачей, писатель изучает многочисленные источники информации и преобразует полученные оттуда данные в пользовательскую документацию. Источников у нас много. Самый главный — это технический проект (ТП), которые пишут бизнес-аналитики ещё до начала разработки. ТП — это закон для разработчиков, тестировщиков и технических писателей. В идеале всё должно быть реализовано именно так, как написано в ТП. На деле же оказывается, что итоговая реализация отличается от ТП. Вы знаете, как это бывает: что-то не учли, что-то поняли неправильно, что-то оптимизировали… Для того, чтобы узнать, как на самом деле всё было реализовано, мы используем техническое описание (ТО), которое пишут разработчики. Там есть больше технических подробностей, описаны изменения конкретных типов данных и таблиц в БД, приведены алгоритмы работы процедур серверного кода, приведены скриншоты добавленных или изменённых окон в клиентских приложениях. Без ТО нам было бы очень трудно написать полноценную документацию. К сожалению, разработчики иногда откладывают написание ТО на самый последний момент.
Есть ещё один важный источник — описание настроек интеграционного тестирования. Там подробно описаны все настройки, которые нужно сделать в системах, чтобы пройти все тестовые сценарии (тест-кейсы). Этот источник незаменим для написания руководств по настройке.
ТП, ТО и описание настроек — это основные источники, из которых писатель получает информацию. Но есть ещё множество дополнительных: исходный код серверных процедур и клиентских приложений, XML-описания параметров, страницы в базе знаний Wiki, наконец — вопросы разработчикам и тестировщикам в мессенджерах. Ну и, конечно, сами системы — их web-интерфейс, клиентские и серверные приложения.
Задача писателя — объединить всю полученную информацию и написать простую, понятную и хорошо структурированную документацию о системе или решении. Тут нужно быть очень внимательным — ничего не перепутать, не забыть, описать именно то, что было реализовано. Писатель должен самостоятельно разобраться во всех особенностях реализации, понять все алгоритмы и принципы работы системы от начала и до конца. Только так получится хорошая и качественная документация.
Работа технического писателя не такая однообразная, как может показаться со стороны. Мы пишем очень разные документы — у нас есть и справочники с большими таблицами параметров или полей БД. Есть руководства пользователя с подробным описанием каждой кнопки интерфейса. Есть руководства администратора со множеством технических подробностей о работе и установке системы. Но самый сложный, и при этом самый интересный, тип документа — это руководство по настройке. В нём комплексно описывается реализация определённого решения в разных системах и подробно объясняется что и где нужно настроить, чтобы это решение заработало. Писателю приходится писать разные типы документов — сегодня часами описывать один за другим параметры системы, а завтра думать над тем, как понятнее и проще описать алгоритм работы решения в руководстве по настройке. Но в любом случае писатель должен быть внимательным, аккуратным и педантичным.
Технический писатель должен:
- хорошо разбираться в своей профессиональной области;
- свободно владеть языком, на котором готовит документацию, составлять тексты без орфографических, пунктуационных и стилистических ошибок;
- иметь представление о программировании, вычислительной технике, информационных продуктах;
- быть в курсе, чем занимаются коллеги смежных специальностей;
- владеть компьютером на уровне уверенного пользователя, знать специальные программы по редактированию текста, верстке и web-дизайну;
- уметь в короткие сроки осваивать новые компьютерные программы и их обновления;
- владеть техническим английским языком;
- иметь навыки самоорганизации и планирования работы.
Рассмотрим, какими навыками и чертами характера должен обладать технический писатель. Конечно, точный список сильно зависит от компании и рода её деятельности. Разберём на примерах и отметим основные моменты, которые дадут понимание, в каком направлении двигаться.
Представь ситуацию: в офисе крупной IT-компании разработали новый веб-сервис. Возможна ситуация, когда проект развивают и поддерживают не те люди, которые его разрабатывали. В таком случае, грамотная документация очень облегчает жизнь, ведь не требуется изучать проект методом «тыка».
Поэтому отдел разработки приглашает технического писателя, чтобы обсудить работу над документацией. Подобных обсуждений может быть много. Причём, часто по инициативе писателя, ведь в процессе работы всегда находятся спорные вещи, которые требуется уточнить.
Согласно Общество технической коммуникации (STC), профессии технического общения и технического письма впервые упоминались в Первая Мировая Война,[4] когда техническая документация стала необходимостью для военных целей. Название должности появилось в США во время Второй мировой войны,[5] хотя только в 1951 году была опубликована первая реклама «Требуется помощь: технический писатель».[6] Фактически, титул «Технический писатель» не добавлялся в Справочник по профессиональной занятости Бюро статистики труда США до 2010 года.[7] В 1940-х и 50-х годах были наняты технические коммуникаторы и писатели для подготовки документации для военных, часто включающей подробные инструкции по новому вооружению. Другие технические коммуникаторы и писатели были вовлечены в разработку документации для новых технологий, которые были разработаны примерно в это время. По словам О’Хара:[8]
Война была важнейшим двигателем научно-технического прогресса. Медицинский корпус армии США боролся с малярией в джунглях Панамы, химический корпус продвигал химические достижения в области взрывчатых веществ и ядовитых газов (и средств защиты от них), инженерный корпус Манхэттенского округа буквально совершил качественный скачок в понимании физики и Авиационный корпус был пионером в области авиационного дизайна.
В начале своей профессии большинство технических писателей работали в офисе с командой других писателей. Как и современные технические писатели, они провели первичное исследование и встретились с профильными экспертами, чтобы убедиться, что их информация является точной. Во время Второй мировой войны одной из наиболее важных характеристик технических писателей была их способность соблюдать строгие государственные требования к документам.[9] После войны появление новых технологий, таких как компьютеры, позволило техническим писателям работать в других областях, создавая[10] «Руководства пользователя, краткие справочные руководства, руководства по установке оборудования и шпаргалки». В послевоенный период (1953-1961) технические коммуникаторы (в том числе технические писатели) заинтересовались «профессионализацией» своей области.[11] По словам Мэлоуна,[12] технические коммуникаторы / писатели добивались этого, создавая профессиональные организации, развивая «специализированный комплекс знаний» для этой профессии, навязывая этические стандарты техническим коммуникаторам, инициируя разговор о сертификации практикующих специалистов в этой области и работая над аккредитацией образовательных программ в этой области.
Профессия продолжала расти — по словам О’Хара, профессия писателя / редактора, включая технических писателей, увеличилась на 22% в период с 1994 по 2005 год.[13] Современные технические писатели работают в самых разных контекстах. Многие технические писатели работают удаленно, используя VPN или общаться со своей командой через видеотелефония платформы, такие как Skype или Увеличить. Другие технические писатели работают в офисе, но делятся контентом со своей командой через сложные системы управления контентом которые хранят документы в Интернете. Технические писатели могут работать над правительственными отчетами, внутренней документацией, инструкциями по техническому оборудованию, встроенной справкой в программном обеспечении или системах или другими техническими документами. По мере развития технологий круг возможностей для технических писателей будет расширяться. Многие технические писатели отвечают за создание технической документации для мобильных приложений или справочной документации, созданной для мобильных или веб-приложений. Они могут нести ответственность за создание контента, который будет просматриваться только на портативном устройстве; большая часть их работ никогда не будет опубликована в печатном буклете, как техническая документация прошлого.
Обязанности технического писателя
Должностные обязанности технического писателя во многом зависят от того, чем занимается работодатель. К основным обязанностям относятся:
- Разработка технической документации (руководств пользователя и администратора, правил эксплуатации, ТУ, ТЗ, технических паспортов и прочих документов) в соответствии с требованиями ГОСТ и другими стандартами.
- Проверка и корректировка технической документации, поддержание ее в актуальном состоянии.
- Подготовка графических схем по заданным параметрам.
- Анализ новых программных продуктов и их тестирование.
- Сбор информации у всех участников процесса: заказчиков, разработчиков, дизайнеров, тестировщиков и менеджеров.
Также должность технического писателя может включать в себя дополнительные функции:
- Подготовка материалов технических презентаций.
- Обучение работе в новых программных продуктах и поддержка пользователей.
- Участие во внедрении программных продуктов.
- Составление документации на английском языке.