Профессия "Технический писатель", или "Рыцари клавиатуры"

Оптимальным, но трудным для исполнения вариантом является дополнение инструкции набором кейсов, описывающих как решить с помощью вашего продукта самые частые производственные задачи (например, как внести в базу 1С новую товарную позицию). Сложность здесь в том, что для этого вам придётся глубоко вникнуть в суть задач отраслевого специалиста, который будет использовать в работе вашу программу.

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

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

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

В основном сюда относятся операторы различных промышленных установок, будь то станки с ЧПУ, врачи-диагносты, или операторы любых других сложных механизмов. При высокой квалификации подобных работников, у большинства из них есть «профессиональная привычка» к оборудованию, на котором они работали ранее (возможно, многие годы). Поэтому они, зачастую, с недоверием относятся к новой технике, хотя и приветствуют её обновление.

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

Чаще всего эта документация поставляется в печатном виде, что нужно учитывать при оформлении текста.

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

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

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

Если речь об описании баз данных (далее: БД), то описываются все таблицы БД, их поля, строится карта взаимодействия (графическая схема БД). Другие данные для описания таблицы не требуются — специалисту по работе с ней упомянутых сведений будет более чем достаточно.

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

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