Чем занимается технический писатель

Технический писатель в ИТ

Многие только слышали про должность технического писателя, но не понимают, чем он занимается и что он пишет. Другие – работодатели – считают, что техническое написание материала может выполнить любой ИТ-специалист. Я имею опыт в ИТ в направлении системного администрирования около 15 лет, на каждом месте работы писал сначала инструкции для себя, потом улучшал их качество, со временем писал статьи для разных блогов. Сейчас уже насчитываю около 80 статей. В какое-то время я официально занимал должность ИТ-писателя. Теперь решил поделиться своими знаниями, списком программного обеспечения и некоторыми наблюдениями.

▍ Когда ИТ-писатель необходим компании

▍ Обучение

Обобщённо, технический писатель является творческой личностью. Этому направлению трудно где-то научиться. Здесь должно быть особое мышление. У меня множество знакомых высококвалифицированных ИТ-специалистов, которые совершенно не склонны к общению со сцены, к обучению коллег. И дело даже не в желании, а в качестве этих обучающих мероприятий, тем более через “бумагу”, а не на пальцах и голосом. В результате получается очень скудный и малопонятный материал, который даже трудно назвать инструкцией, полезной документацией. Они просто переносят на бумагу код программы, названия функций информационных систем, множество аббревиатур без необходимого пояснения, без структурирования.

Конечно, к этому не сразу приходишь, этим “делом” нужно некоторое время заниматься, посвятить себя. На страницах Хабра так и писали, что начнёт получаться спустя 20-30 статей. Я скажу, что это полная правда. У меня стало получаться примерно после 10 статьи (на тот момент я так думал). Примерно после 30й статьи у меня прям мысли стали структурированными, соответственно, материал становился более качественным. Я уже сам мог давать многим специалистам рекомендации, замечал ошибки в текстах документов, статей блогов, видел неопытность авторов.

▍ Принцип написания инструкций

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

▍ Список программного обеспечения для ИТ-писателя

Foxit PDF Editor (или любые другие pdf-редакторы типа Nitro PDF Professional, Soda PDF Professional или же OpenOffice, LibreOffice) — в нём легко можно вставлять целиком страницу из другого pdf-файла, писать и форматировать текст, добавлять картинки. После создания нескольких pdf-страниц (отдельных файлов) Foxit PDF Editor позволяет их последовательно скрепить в один документ. Для этого необходимо зайти в меню File, выбрать пункт Join, в появившемся окне нажать кнопку Add Files и выбрать необходимые pdf-файлы для слияния, а затем нажать кнопку Join.

Dr.Explain – эта программа для создания справочной системы, устанавливается на компьютер, есть поддержка русского языка, имеет дружелюбный интерфейс, проста в использовании, наличие платной и бесплатной версий. В Dr.Explain с самого начала уже имеется основа для составления документа, то есть панель, содержащая структурированное дерево (Оглавление, Раздел 1, Раздел 1.1). При выделении одной из ветки, можно добавлять новые пункты. Также доступно форматирование текста, вставка картинок, просмотр и экспорт в 4х форматах: CHM, HTML, Doc, PDF.

Результат экспорта в HTML-формат

MediaWiki – это движок для создания веб-инструкций, заметок, справок, различных текстовых описаний, лекций и конспектов. Имеется большое количество расширений, аутентификация, возможность оставлять комментарии. Требуется наличие LAMP.
Чтобы в MediaWiki добавить новый раздел, нужно выделить существующий раздел, нажать кнопку Править, вписать название и нажать кнопку Записать страницу.

Atlassian Confluence – продукт с веб-интерфейсом для ведения онлайн-документации целой командой и одновременного редактирования текста. Имеет поддержку большого количества языков, приятный интерфейс. Под конкретную задачу сначала создаётся пространство, то есть выделяется отдельный блок, например, для каждой команды (отдела) или для разных проектов. В пространстве создаются страницы, выбирая необходимую тематику из списка:

В Confluence доступно простенькое меню форматирования текста. Например, чтобы изменить шрифт текста на машинный, нужно нажать кнопку Редактировать, затем справа нажать на “<>”, в коде найти фрагмент текста и применить параметры CSS:

Кроме этого, текст можно выделять и с помощью макросов (на панели нажать “+”). Для команд и программного кода макрос называется Блок кода.

Чтобы добавить какое-то важно оповещение, применяется макрос Внимание, а чтобы подчеркнуть или выделить информационный текст, применяется макрос Информация.

Draw.io – инструмент для создания всевозможных блок-схем, бизнес-макетов, карт сайтов, ментальных карт, отношений сущностей, программных блоков и другого. Здесь богатый выбор иконок, связей, сопутствующих элементов для составления красочных и наглядных схем. В онлайн-версии можно производить совместное редактирование с другими пользователями, осуществить экспорт в форматы JPG, PDF, PNG, SVG, XML, VSDX, HTML, установить связь с Google Диском, Google Workspace, Dropbox, Confluence и Jira.

В моём случае создавались схемы связей сетевого оборудования между несколькими объектами, схемы отображения серверного и клиентского оборудования, схемы работы отдельных функций CRM-системы, традиционной и IP-телефонии в паре, структур Active Directory, схемы работы локальных и облачных сервисов.

Одним из примеров — нужно было отобразить работу балансировщика нагрузки веб-серверов EC2 сервиса Amazon вместе с функцией автоматического масштабирования.

Другой пример – отображение расположения оборудования в серверных шкафах. Выбираем шкаф в разделе Rack/General, патч-панели, холдеры для кабелей. Из меню Rack/APC добавляем источники бесперебойного питания APC Smart UPS, из меню Rack/Aruba/Switches добавляем в шкаф коммутаторы, маршрутизатор, шлюз, из меню Rack/HP — сервера. Таким образом получилось расположение оборудования в первом приближении. Конечно, на схеме в шкафу можно добавлять ещё оборудование, двигать его, добавлять текстовые пометки, изменять цвет.

Здесь ещё удобно отдельно отобразить патч-панель, свитчи, увеличить их до удобного вида, чтобы для портов сделать цифровые надписи, которые будут соответствовать какому-то подключённому устройству. Добавив таблицу, можно ещё вписать названия портов и компьютеров, ФИО сотрудника, номер кабинета и другое.

Следующим примером покажу сложный вариант работы системы Graylog, к нему пришли, конечно, не сразу. Ранее сервисы стека для работы всей системы Graylog были размещены на нескольких серверах. Со временем при большой нагрузке произошло разделение: создание двух кластеров и размещение серверов в разных ЦОДах. После полной наладки всей системы уже возникла необходимость создания актуальной схемы.

MS PowerPoint — презентация включает в себя текст и наглядное представление информации (картинки, диаграммы, схемы, алгоритмы, таблицы, звуковое и видеосопровождение), она помогает максимально понятно донести всю суть вопроса до слушателя на собрании, форуме, презентации.

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

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

Создание слайдов в MS PowerPoint происходит легко, а также удаление, перемещение, изменение места — при помощи мыши и контекстного меню в левой панели. Работа с текстом в PowerPoint такая же несложная, как и в Word, используются те же кнопки и приёмы форматирования, также можно вставлять диаграммы из таблицы Excel, загружать картинки с локального диска.

Стандартное оформление презентации очень простое и скучное. В PowerPoint есть несколько меню для применения различных эффектов. Рассмотрим их.

В меню Дизайн имеется множество готовых шаблонов, чтобы фон слайдов был более оригинальным.

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

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

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

Простой способ озвучить слайд – заранее записать голосовое сообщение, в меню Вставка нажать кнопку Звук и выбрать пункт Аудиофайлы на компьютере, выбрать соответствующий файл.

Если необходимо показать презентацию в виде ролика, то нужно сохранить презентацию специальным способом. Для этого заходим в меню Файл->Экспорт->Создать видео->нажать кнопку Создать видео.

MS Paint + FastStone Image Viewer — Почти всю обработку скриншотов я делаю в стандартной графической утилите Paint, которая встроена в ОС Windows. Мне достаточно в ней обрезать кусок картинки, добавить текст и стрелки, соединить 2 скриншота, выделить кнопку, заголовок, вкладку другим цветом. А в FastStone Image (при необходимости) я добавляю яркость и контрастность для картинки.

▍ Направления в работе и обязанности

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

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

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

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

В одном направлении я не подходил, так как не имел опыта работы с API. В некоторых компаниях технический писатель занимается документированием API. Для этого используется продукт Swagger [Swagger (OpenAPI 3.0), Руководство Spagger UI]. Ещё один популярный продукт для этих целей – Postman [Введение в Postman].

Вывод: техническим писателем не так-то просто уж и стать. Такой специальности нет в ВУЗах. Это направление должно нравиться, в нём нужно быть грамотным, технически подкованным. Навыки технического письма вырабатывается годами, но зато потом можно быть востребованным специалистом.

Источник

Чем занимается технический писатель: опыт IT-компании Lad

Авторизуйтесь

Чем занимается технический писатель: опыт IT-компании Lad

Рассказывают технические писатели IT-компании Lad Екатерина Каляева, Анна Назолина, Ксения Скорынина

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

Технические писатели и knowledge management

Технические писатели в компании выполняют разную работу. Например, часть команды занята в сфере управления знаниями внутри проектных групп. Она не привязана к единственному продукту или команде, а занимает позицию как бы вне конкретного проекта и готова подключиться к любому из них. Основная единица документации — статья в базе знаний. Статьи объединяются в проекты, при этом их внутренняя структура одинакова.

Так выглядит база знаний Центра Разработки. Слева — проекты и дерево статей, справа — непосредственно тексты статей.

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

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

Технический писатель по канону

«Классический» технический писатель в компании занимается написанием не только внутренней документации на проекте, но и внешней — для заказчиков.

Внутренняя документация — это, например, описание админки, процесса продажи/возвратов/рассрочки, БД MongoDB. А внешняя обычно включает в себя описание верхнего уровня проекта: цели, требования, бизнес-эффект, а также мануал для работы сотрудников с разрабатываемым продуктом. Таким образом, технический писатель играет важную роль в команде вне зависимости от его специализации. Это не просто сотрудник, который пишет документацию, исходя из своей точки зрения и предпочтений. Техписатель-профессионал может почерпнуть «тайную» информацию от коллег-разработчиков и, что важно, принимает точку зрения каждого из коллег.

О том, почему документация — это непросто

При написании документации мы используем множество источников информации: это и собственные знания, и знания коллег, код, вся ранее написанная документация, если такая есть, и требования заказчиков. Самая важная задача здесь — это побывать в роли каждого сотрудника:

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

Инструменты must-have

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

Как выполнять план без нервов

Каждый день из работы технического писателя — особенный. Иногда мы несколько дней вдумчиво работаем над написанием одной статьи. А порой все горит и появляются новые задачи, которые нужно оперативно решать. Ежедневно мы проверяем доску Agile, оцениваем количество оставшихся задач и их статус. Выбрав приоритетные на день, прописываем их детально в карточке задачи, а затем переносим эти микрозадачи в свой Google-календарь. Так они удобно комбинируются с митингами и другими запланированными мероприятиями. Таким образом удается эффективно распределять свое время и не хвататься за все сразу, а план на день успешно выполняется.

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

Жизненные циклы задач

Один из важнейших инструментов технического писателя в нашей компании — это трекер задач YouTrack. В нем у нас есть своя Kanban-доска, на которой мы видим все задачи, которые лежат в бэклоге, находятся в работе, приостановлены или готовы. При помощи флажков мы выставляем задаче приоритет, в некоторых случаях обозначаем дедлайн. Пока мы работаем над задачей, оставляем к ней комментарии о том, что уже сделано, что еще предстоит, важные ссылки и контакты людей, а также ведем обсуждение.

С помощью такой доски удобно менять статус задачи и делать к ней пометки.

Задачи обычно приходят по нескольким каналам. В первую очередь, это техлид Центра Разработки или менеджер проекта. Мы практикуем регулярные встречи с ними, обычно в формате видеозвонка, чтобы обсудить прогресс по задачам: какие выполнены, какие сейчас в процессе, а что вызывает трудности. Другой путь формирования задач — это канал #docs в корпоративном мессенджере Slack. Мы используем его как инструмент коммуникации с командами: этой самый быстрый способ для них спросить технических писателей о чем-то или поручить написание статьи. В том же канале мы объявляем последний новости, связанные с базой знаний, и делаем анонсы статей.

Тон фидбека мы обычно определяем по реакциям в Slack.

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

Каждая задача проходит примерно одинаковый жизненный цикл. Вначале мы определяем цель и целевую аудиторию статьи. Сформулировав вопросы, отправляемся с этим к эксперту в предметной области (SME), формируем черновик статьи. После нескольких итераций, в течение которых редактируем контент и его представление, мы показываем готовый текст всем заинтересованным лицам. Наконец, документ или статья публикуются, и происходит обсуждение того, как мы будем поддерживать актуальность.

3 сигнала, что задачу можно закрывать

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

Следуя своей тактике, технические писатели IT-компании Lad за полгода обработали около 40 документационных задач и создали свыше 100 статей в базе знаний Центра Разработки.

Источник

Технический писатель: кто это, обязанности, зарплаты и как им стать в 2021 году. Обзор профессии.

Кто такой технический писатель?

Технический писатель (technical writer) — это специалист, который преобразует сложные и технически трудные письменные материалы в четкую и лаконичную документацию, которую будет читать целевая аудитория. Они собирают и разрабатывают техническую информацию для создания инструкций по обслуживанию и эксплуатации, технических и инструктивных руководств, журнальных статей и другой документации для производителей, проектировщиков и клиентов. Технические писатели также могут писать техническое задание (ТЗ).

Что делают технические писатели и чем занимаются?

Обязанности на примере одной из вакансий:

Что должен знать и уметь технический писатель?

Требования к техническим писателям:

Востребованность и зарплаты технических писателей

На сайте поиска работы в данный момент открыто 1 010 вакансий, с каждым месяцем спрос на технических писателей растет.

Количество вакансий с указанной зарплатой технического писателя по всей России:

Вакансий с указанным уровнем дохода по Москве:

Вакансий с указанным уровнем дохода по Санкт-Петербургу:

Как стать техническим писателем и где учиться?

Варианты обучения для технического писателя с нуля:

Ниже сделали обзор 15+ лучших онлайн-курсов.

15+ лучших курсов для обучения технического писателя: подробный обзор

1 место. Курс «Технический писатель» — Skillbox

Технический писатель — это профессионал, который умеет простым языком описать сложные процессы. Например, как пользоваться техническим оборудованием на заводе или CRM-системой в компании. Он составляет руководства, документацию, инструкции, пишет технические задания (ТЗ) для исполнителей.

Кому подойдёт этот курс:

Чему вы научитесь:

Программа

Вас ждут онлайн-лекции и практические задания на основе реальных кейсов.
23 модуля, 54 урока

Основные курсы

Дополнительные курсы

Дипломные проекты

Диплом Skillbox

Подтвердит, что вы прошли курс, и станет дополнительным аргументом при устройстве на работу.

2 место. Курс «Технический писатель» — ФинКонт

Цели семинара/курса:

Профессиональный стандарт «Технический писатель»: содержание и требования:

3 место.Курс «Технический писатель» — B-seminar

Цель курса:

Техническая документация и технический писатель: основные термины и понятия. Введение в проблему.

Единые стандарты документирования.

Виды и стили технических текстов.

Средства и методы создания технических текстов.

Приёмы работы с техническими текстами.

Создание векторных изображений и контроль ошибок в объемных документах.

Процесс перевода технической документации (на примере английского языка).

Программное обеспечение в работе технического писателя.

Курс «Технический писатель. Разработка технических текстов и документации» — ЦНТИ Прогресс

Для кого:

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

Программа:

Источник