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

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

• Пример 1. Наличие большого количества сервисов для их схематического и текстового описания. Не у каждого продукта имеется подробная документация, а имеющаяся – потеряла актуальность при перенастройке сервисов под нужды бизнеса. Некоторые производители могут только поверхностную информацию предоставить, а по конкретике от “а” до “я” — приглашают на обучающие платные курсы. В этом случае компания может послать на обучение какого-то специалиста, который в дальнейшем настроит продукт и устно передаст информацию писателю для составления инструкций.
• Пример 2. Компания получила новые проекты и дальнейшее расширение, набрала большое количество новых сотрудников, произвела интеграцию многих крупных сервисов, самописные программные продукты разветвились. Документация помогает сотрудникам компании быстро вникнуть в работу проекта и меньше звонить другим специалистам с возникающими вопросами.
• Пример 3. Когда долгое время ИТ-сотрудники компании передают информацию между собой в устной форме. Это чревато при забывчивости, переходе в другие отделы, отсутствии на рабочем месте, увольнении.
• Пример 4. Компания сама является производителем какого-то продукта. Чтобы его продать заказчику, необходимо иметь инструкции по эксплуатации.
• Пример 5. Когда у имеющихся специалистов нет навыков грамотного составления текста. Это не значит, что он плохой специалист. Далеко не каждый может правильно, красиво, лаконично, доступно изложить технический материал на бумаге.

▍ Обучение

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

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

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

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

1. Определяемся, для кого создаётся инструкция: конечные пользователи, сотрудники среднего звена, руководство, общая для всех, для клиентов.
2. Пишется тема или заголовок.
3. Создаются колонтитулы, где размещаются фирменные иконки, девиз, короткое название темы инструкции, а также добавляется нумерация страниц.
4. Если используется профессиональная терминология, то необходимо подготовить перечень терминов с расшифровкой.
5. Далее нужно продумать организационную структуру каждого раздела. Одним из удобных вариантов может быть составление скелета инструкции. Например, набросали 5-10 пунктов, пронумеровали и дали им названия. Это вносит большую ясность, что за чем описывать и что необходимо ещё добавить. Дальше идёт описание каждого пункта.
   
   Если текста много, то лучше разбивать на абзацы или сделать дополнительный пункт, так как сплошной текст труднее читать. При описании лучше указывать простые и понятные действия, типа: нажатие кнопки “Экспорт”, использовать меню “Параметры”, а также результат: получим данные в виде таблицы или появится мастер настроек.
6. При описании какого-либо функционала продукта крайне желательно прикреплять подтверждения в виде таблиц, схем, алгоритмов, картинок, скриншотов. Наглядность даёт большее понимание.
7. Во время изложения своих мыслей необходимо задавать самому себе некоторые вопросы типа: а зачем?, действительно ли так?, подходит ли? Если описание в тексте раскрывает вопрос, то движение идёт в правильном русле.
8. Различные выделения текста (жирный, подчёркнутый, наклонный, другим шрифтом и размером) бросает внимание на нужные фразы, настройки, действия. Также желательно отделять какие-то блоки текста тонкими линиями или готовыми маркерами. Например, такие блоки, как “Для справки”, “Примечание”, “Важно”, “Внимание” и другие.
9. По завершении работы над инструкцией (обязательно) начинается работа над ошибками. Нужно проверить, читается ли текст легко, самому ли всё нравится, затем дать на проверку такому же специалисту, а после этого — разослать нескольким работникам и узнать, всё ли понятно.
10. После одобрения word-овского варианта инструкции желательно оформить её в pdf-формате.

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

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:

<span style= “font-family: courier new; font-size: 110.0%;” > команда 1 </span>

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



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



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].

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