 |
|
|
|
Технический писатель в ИТ. Роль в команде разработки
Технический писатель в ИТ Многие никогда не слышали о профессии технического писателя, хотя количество подобных вакансий в разных отраслях растет с каждым годом. А те, кто слышал, зачастую имеют о ней неверное представление
Еще в девятом классе гимназии я озадачилась вопросом: кто я – технарь или гуманитарий? Дисциплины этих двух направлений мне были одинаково интересны, однако среди всего многообразия выделить что-то одно и уйти в это с головой не получалось. Когда пришлось выбирать направление для последних двух лет обучения, я остановилась на гуманитарном классе. Мне нравилось углубленное изучение иностранных языков и литературы, однако мысль о том, чтоматематика мне интересна не меньше, не давала покоя. В итоге ходила на школьные курсы по математике и физике филиала МГУ, а после поступила в Томский университет систем управления и радиоэлектроники на специальность инженер промышленной электроники. Специальность исключительно техническая, так что появилась необходимость поддерживать знания иностранных языков, и я решила получить дополнительное образование по специальности технический переводчик в сфере профессиональных коммуникаций. Что касается профессионального развития, то со второго курса начала работать фрилансером-переводчиком, однако продолжала искать сферу, которая объединила бы стремление работать не только с языками, но и с технологиями. По счастливой случайности, увидела вакансию технического писателя в UNIGINE. Все сошлось – было необходимо владение английским языком и понимание теоретических основ программирования. UNIGINE – томская ИТ-компания, первостепенная миссия которой – программная разработка реал-тайм-платформы 3D-графики, на основе которой клиенты создают различные индустриальные проекты, требующие реалистичного изображения и интерактивного взаимодействия. Сама платформа представляет собой исходный код на С++, однако разрабатываются также и вспомогательные продукты: визуальный редактор, SDK-браузер для управления проектами, консольные инструменты. Помимо самой платформы, есть собственные продукты на базе движка – симуляторы, бенчмарки для тестирования производительности видеокарт, игры, а также множество веб-ресурсов, как для внешнего, так и для внутреннего использования. Для каждого продукта в той или иной форме нужна документация или обзорные статьи, их созданием и занимается технический писатель. Как любой другой компонент, документация является частью продукта и характеризует компанию, поэтому наша цель – сделать ее как можно лучше. Кто такой технический писатель, или Технический писатель – не переводчик Когда я говорю, кем работаю, многие люди думают, что работа заключается в переводе текстов. Отчасти они правы, вот только перевод осуществляется не с одного языка на другой (см. рис. 1). Переводчик получает уже кем-то написанный текст, пользуется словарем, специальными программами и головой и на выходе выдает текст на другом языке с сохранением смысла.
Рисунок 1. Различия между переводчиком и техническим писателем Технический писатель же на входе имеет какой-то продукт, его исходный код, внутреннюю базу знаний и нескольких разработчиков, каждый из которых отвечает за какую-то отдельную часть программы. Однако вся эта информация все еще является неполной, и нужно уметь искать недостающие данные, чтобы на выходе получился полезный читабельный материал. А польза от технического писателя следующая: пользователь получает не просто продукт, а продукт синструкцией. Если непонятно, как извлечь максимум из возможностей продукта, то пользы от него будет мало. На помощь приходит технический писатель – связующее звено между разработчиком и конечным пользователем. Иными словами, если непонятно, как чем-то пользоваться и нет возможности это узнать, – толку ноль. Было бы здорово, если бы интерфейс продукта позволял разбираться во всем сходу, но порой предметная область слишком сложная. Если говорить о том, что конкретно входит в задачи технического писателя, список может получиться довольно большим. Помимо очевидного умения работать с техническим текстом и знания стандартов документирования, нужно неплохо владеть графическими редакторами, иногда записывать видео, переводить, писать рекламные тексты, общаться с пользователями. И это только формат результата работы. Еще надо откуда-то получить исходную информацию, которую, собственно, и нужно описывать. Об этом ниже. Рабочий процесс Теперь немного расскажу про сам процесс документирования. Перед написанием статьи важно понять, будет ли от нее польза, и если будет, то кому (то есть определить целевую аудиторию). Затем необходимо провести интервью сразработчиком, в котором он расскажет о проделанной работе. Большой ошибкой будет считать, что разработчик мыслит в той же плоскости, что и технический писатель, и, значит, в подробностях объясняет, как его программа работает, в товремя как технический писатель только структурирует материал, грамотно пишет, оформляет и снабжает иллюстрациями. Если бы все так и было, компании достаточно было бы нанять корректора. Важно понимать, что разработчик может принимать многое как данность и думать, что люди и так все понимают. Он может опускать «ненужные детали» или вообще говорить: «Этого знать никому не надо!» Однако бывает и наоборот: ребята начинают рассказывать о низкоуровневых внутренностях программы, которые только перегружают голову пользователя. Ответственность за составляющие будущей статьи как раз и ложится на технического писателя. Задав правильные вопросы и узнав все от разработчика, необходимо понять, нужна ли вся полученная информация в документации. Часто бывает так, что смысла документировать нет, так как через месяц точно данная информация будет неактуальна или дополнится. Такие задачи переходят в хранилище задач. Далее, если информация актуальна, техническому писателю надо побыть тестировщиком – воспроизвести функционал в своем окружении, проверить, все ли работает правильно. Часто вместе с программистом или самому необходимо писать примеры кода, обычно это тоже делается до написания статьи. И только изучив все связанные статьи, чтобы изменение было зафиксировано по всей документации, можно переходить к последнему пункту – непосредственному созданию статьи, что по сравнению с предыдущей подготовкой занимает нетак много времени. Если есть возможность, желательно отдать готовую статью на вычитку коллегам, чтобы получить взгляд со стороны. Процентное распределение времени показано на рис. 2.
Рисунок 2. Процентное распределение времени при документировании Объемы Хочется упомянуть о фактических объемах работы. На данный момент в компании 13 активных разработчиков (каждый из которых работает за двоих) и три технических писателя. По большому счету, список задач технических писателей можно разделить на две части: это технический долг (функционал, добавленный ранее и не задокументированный или устаревший, но не обновленный) и новая документация. В ней описываются возможности, которые станут доступны только в следующем релизе. Для каждого релиза существует отдельная версия документации, которая включает в себя около 1000 статей (больше половины из них – справочник API с описанием функций и примерами кода). Весь материал всегда пишется для трех языков программирования (C++, C# и UnigineScript). Большая часть статей остается неизменной, однако для каждого релиза так или иначе обновляется или дополняется 30% документации. Целевая аудитория Задачей технического писателя является определение сферы знаний пользователя и написание инструкции на понятном языке. Пользователи бывают продвинутые, и для них достаточно, например, просто привести пример кода. А дляновичков необходимо расписывать каждый шаг, что, как и почему, не полагаясь на то, что обо всем можно догадаться. Когда технический писатель долгое время работает с продуктом, он начинает многое воспринимать как данность. Важно уметь переключаться и задумываться о том, на каком уровне понимания находится пользователь. Помимо этого, у пользователей еще и разная профессиональная квалификация. Конкретно в нашем случае основными читателями технической документации являются программисты и 3D-художники. Читателями промо-материалов являются потенциальные покупатели и просто люди, интересующиеся технологиями. К каждому типу читателей нужен подход и своеобразная подача материала. В следующем разделе я расскажу, какие жанры документации есть у нас. Жанры документации Ментальная модель Ментальные модели необходимы для общего развития и знакомства с каким-либо понятием (например, что такое «двойная точность координат»). Стиль написания – повествовательный, похож на стиль Википедии. В такой статье важно ввести понятие, описать базовые сущности и их взаимосвязи, показать, как работает каждая подсистема в отдельности (см. рис. 3).
Рисунок 3. Ментальная модель документации Руководство пользователя Для тех, кто работает в основном с визуальными редакторами (в нашем случае – 3D-художники), необходимо писать руководства пользователя. Такой материал обычно представлен в виде текста и оснащен иллюстрациями. Следует иметь ввиду, что пользователь, возможно, в первый раз видит визуальный редактор. Важно указывать краевые значения параметров и влияние одних параметров на другие, чтобы не запутать читателя (см. рис. 4).
Рисунок 4. Пример руководства пользователя Справочник API Если статья предназначена только для программистов (справочник API, включающий в себя описание классов, функций и аргументов), стиль написания будет соответствующий – все важные технические детали будут учтены, приведены примеры кода, описаны ограничения и краевые случаи. К тому же зачастую подразумевается, что многие вещи программисты знают и так, и в базовые подробности вдаваться не нужно. Для такого типа документации важен еще быстрый поиск и удобная структура, так как к справочнику, в отличие от других типов статей, обращаются очень часто (см. рис. 5).
Рисунок 5. Пример справочника API Туториал По моему опыту, самым удобным методом подачи материала является туториал, или пошаговое руководство. При воспроизведении туториала вопросов, как правило, не возникает, так как процесс выполнения необходимого действия описан от начала и до конца. Видеотуториалы пользуются еще большей популярностью (см. рис. 6).
Рисунок 6. Пример туториала Промо-материалы Промо-материалы нужны для того, чтобы познакомить читателя с возможностями движка, заинтересовать. Писать надо живым, понятным языком. Зачастую эти тексты читают потенциальные клиенты, поэтому текст должен быть продающим. Стандарты Что касается документации в ИТ-индустрии, в отличие от промышленных предприятий, стандартов как таковых у нас нет. Главное правило – написано должно быть по делу и максимально понятно. Сложных предложений и оборотов мыстараемся избегать. У нас есть негласное правило: при написании статьи надо представлять читателем китайского мальчика, английский у которого – не родной язык. Для консистентности шаблонных статей у нас есть внутренние руководства. Что касается работы с техническим языком – в свое время прочитали Microsoft Manual of Style, много полезного оттуда переняли и внедрили во внутренние стандарты (см. рис. 7).
Рисунок 7. Пример документации Качество За месяц наша команда должна успевать так или иначе обновить каждый раздел документации, и следить за качеством проделанной работы крайне сложно. Важным мерилом является частота заявок в службе поддержки, которые связаны с документацией. Однако если их нет, это не значит, что проблем и вопросов у пользователей не возникает. Чтобы узнать, какие задачи приоритетнее, необходимо добиваться от клиентов обратной связи. Также все новички в компании сначала неделю читают документацию и потом присылают свои замечания. Это очень полезно, так как можно узнать мнение о документации от специалистов из разных отраслей. Еще очень важно часто общаться с менеджерами продуктов – им, как никому другому, известно, чего не хватает пользователю. Повышение квалификации Ремеслу технического письма в вузах не обучают, по крайней мере в России. В большинстве случаев сотрудники приходят в компанию и учатся у коллег либо по интернет-ресурсам. В UNIGINE было принято решение пройти хотя бы онлайн-курс, и обязательно на английском языке, так как всю документацию мы пишем только на английском. Выбор пал на канадскую бизнес-школу Sprott университета Carleton, которая предлагала четырехмесячный курс обучения азам технического письма и XML-разметки Professional Technical Writing («Профессиональная разработка технической документации»). Мы с коллегой прошли курс от начала до конца, выполнили все задания и даже написали курсовой проект. Из сильных сторон программы я бы отметила знакомство с профессиональными инструментами для технических писателей, а также обучение работе с текстом. Научили правильно структурировать материал, логически связывать параграфы, выделять главное. Что мы не смогли применить на практике, так это тестирование написанных статей. К сожалению, разработка в компании ведется в таком темпе, что выделять несколько дней для тестирования и вычитки документации отделом QA непредставляется возможным. Этим в UNIGINE технические писатели занимаются самостоятельно. Инструменты Что касается инструментов, то ничего необычного у нас нет, практически все пишем в XML. Есть собственная система генерации функций из исходников. Однако техническому писателю необходимо много другого софта: программы дляработы с 2D-изображениями (Adobe Photoshop, Illustrator), 3D-контентом (3ds Max и Maya), среда разработки (Microsoft Visual Studio) и т.д. Особенности профессии Кому же все-таки по душе придется профессия технического писателя? Конкретно в UNIGINE статистика такая: всего за 12 лет было семь технических писателей, а началось все с генерального директора, который писал документацию первые два года сам. До недавнего времени компании было достаточно одного техписателя, но команда растет, и на данный момент нас трое. Девочек получается чуть больше, чем мальчиков, но при собеседовании сотрудников разницы нет никакой, и поток приходящих резюме примерно пятьдесят на пятьдесят. По основному образованию сильно лидируют технари, однако дольше всех технических писателей в истории, в течение пяти лет, отлично справлялась с работой сотрудница с филологическим образованием. Тем не менее при отборе новых кандидатов мы заметили, что предметная область достаточно сложна для гуманитариев. Был случай, когда собеседуемый не знал таких основ математики и информатики, как типы данных и системы координат. В таком случае на обучение человека ушло бы очень много времени.
В целом конкретно при устройстве в нашу компанию требуется общая техническая адекватность и хороший уровень английского языка. Такие профессиональные навыки, как отличное владение языком и умение лаконично выражаться, длятехнических писателей очевидны. Мне хотелось бы рассказать об особенностях работы, чтобы будущие технические писатели понимали, чего стоит ожидать от работы. Технический писатель – специалист широкого профиля. Обычно каждый отдел разработчиков специализируется на чем-то конкретном (написание модуля программы, поддержка веб-ресурсов и т.д.). Очень часто мне задают вопрос, зачем человеку с техническим образованием, например программисту, идти в технические писатели? Я думаю, что эта профессия подходит людям с широким кругозором, тем, кому интересна сфера в целом, но слишком узконаправленным специалистом становиться не хочется. То есть человеку интересно узнавать новое в разных сферах, а не глубоко изучать одну. Однако при большом желании можно развиваться в разных направлениях самостоятельно, параллельно с работой технического писателя (в нашем случае это программирование и 3D-моделирование). Здесь бы я еще отметила причастность к высоким технологиям, возможность работать в компании мечты небудучи разработчиком, но понимая, как все устроено. Мне кажется, в этом и есть уникальность этой профессии. В любом случае, дальнейший путь специалиста определяется его амбициями – чем больше он выкладывается на работе, развивается, узнает информацию, ищет себя, тем стремительнее будет его карьерный рост в любом направлении. Глобальным плюсом профессии я вижу изменение типа мышления. Технический писатель должен уметь видеть картину в целом, мыслить системно. Формируется навык структурирования информации: прежде чем что-то сделать, нужно определить крупную задачу и декомпозировать ее на множество маленьких. Также во время работы развивается навык объяснения сложного простым языком, который очень пригождается и в повседневной жизни. Из желаемых личных качеств при подборе технических писателей мне хотелось бы отдельно упомянуть коммуникабельность и любознательность. Техническому писателю каждый день приходится задавать вопросы разработчикам, просить помощи. Бывает, что всем некогда, на сообщения не отвечают, и приходится быть настойчивее. Зачастую, чтобы о чем-то расспросить, приходится искать нестандартную обстановку, например на кухне за чаем незаметно перевести тему нанужную. В какой-то степени это напоминает работу журналистов. Далеко не всем будет комфортно в таком режиме. Об идеалах Бывают задачи, на которые дается достаточно времени: можно досконально изучить необходимую часть программы, всех опросить, составить план, написать статью, вычитать. Но мне такие не встречались. Почти всегда каждый отдел разработчиков работает над своим собственным проектом, в то время как технические писатели универсальны и должны уметь справляться с любой задачей, причем зачастую в день нужно выполнить несколько задач из разных отраслей. Разработка программного обеспечения типа нашего – бесконечный цикл. Всегда есть планы на будущее: что изменить, что добавить, что переделать полностью. Документация, как спутник продукта, тоже не стоит на месте. Казалось бы, чтонужно для качественной статьи? Изучить материал, протестировать, описать, вычитать, дать почитать кому-либо еще. И вот результат твоей работы готов. Однако в зависимости от частоты релизов (у нас – один – четыре месяца) многое приходится переписывать заново. Важно сохранять спокойствие и оптимистично к этому относиться. Технический писатель – многогранная профессия для тех, кто хочет везде успеть. Здесь важно и умение работать с большим объемом информации, и любовь к людям, и потребность что-то создавать. Но особенным пунктом я бы выделилажелание объяснять и обучать. В этом и заключается магия технических писателей – помочь пользователю максимально быстро разобраться в сложном продукте. |
ОЛЬГА ТУРЧАНОВСКАЯ, ведущий технический писатель в UNIGINE, г. Томск, разрабатывающей собственную 3D-платформу, 
Комментарии отсутствуют
| Добавить комментарий |
|
Комментарии могут оставлять только зарегистрированные пользователи |
|
