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

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

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

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

Поэтому просто напишите простую, качественную и понятную инструкцию и надейтесь, что её прочитают.

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

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

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

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

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

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

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

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

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

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

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

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