Профессия "Технический писатель", или "Рыцари клавиатуры"
- Автор: Михайлов Александр Владимирович
- Год: 2022
- Язык: русский
- Год: ЛЕНАНД
- ISBN: 978-5-9710-5353-8
- Жанр: Прочая компьютерная литература
Электронная книга - «Профессия "Технический писатель", или "Рыцари клавиатуры"». Краткое содержание книги:
Первым шагом будет определение целевой аудитории вашего документа. Основные варианты ЦА были у нас рассмотрены ранее (см. раздел «Основные группы пользователей документации»), поэтому останавливаться на этом повторно мы не будем. Вам же нужно сделать выбор, от которого будут зависеть дальнейшие действия, поскольку поняв, кто будет конечным пользователем вашего текста, вы сможете выбрать стиль изложения, глубину подачи материала и всё остальное. Мы же в своём примере будем писать документ для опытных и корпоративных пользователей.
Вторым шагом будет выбор соответствующего уровня разъяснения. В зависимости от вашей ЦА, потребуется определить, что именно и насколько подробно разбирать в документе, чтобы человек с его предполагаемым набором знаний без труда смог разобраться в вашем тексте. Основные варианты:
1. Человек не знает ничего. По сути, это портрет домашнего пользователя. Ему нужно разжёвывать все действия подробно, сопровождая каждое скриншотом с дополнительными отметками (вроде подчёркивания кнопок, которые нужно нажать).
2. Человек знает систему, но не знает описываемое ПО. Портрет опытного пользователя. Вам нужно рассказать, как пользоваться программой, при этом можно значительно уменьшить размер документа за счёт скриншотов и описания однотипных действий. Но установку нужно описать подробно, можно со скриншотами, ибо ошибка в ней (например, пропуск важного компонента) чревата проблемами в дальнейшей работе. А многие остальные действия можно описывать уже только словами. Этот вариант подходит для руководств пользователей программного обеспечения, которое не требует мудрёной настройки и интеграции с системой (или требует, но для этого есть администратор со своей отдельной инструкцией).
3. Человек хорошо знает и железо, и систему, и при этом легко способен догадаться, как пользоваться вашим ПО. Иными словами, это администратор. Ему нужно подробно описать установку (всё по той же причине её критичности) и настройку вашего продукта (если в них есть тонкости, а в крупных комплексах они есть всегда), процесс его ввода в эксплуатацию и наиболее часто возникающие проблемы (и, если это известно, методы, которыми пользователи эти проблемы администратору поставляют — такая информация очень поможет администратору в работе). При этом обратите внимание, что установку и базовую настройку вы можете описать в руководящем стиле (нажмите, сделайте), то остальную работу с программой нужно описывать в справочном формате: за что отвечает та или иная опция или кнопка, как происходит выполнение основных действий и т. д.
4. Человек написал ПО, которое вы описываете, и тем же будет заниматься тот, кто придёт на его место и будет читать ваш текст. То есть это программист-разработчик. Здесь разъяснять не надо вообще ничего. Только комментировать краткими фразами, давая определения.
В нашем примере мы будем действовать по второму варианту.
Третьим шагом нужно определить необходимый уровень описания. От глубины изложения он отличается тем, что является, по сути, количеством данных, которые писатель выливает на пользователя.
1. Домашнему пользователю нужно предельно подробно описать, как он может выполнить его конкретные задачи, все остальные свойства программы можно привести в конце руководства в справочном формате. Описывать работу программы необходимо с самого начала, нажатия кнопки «Пуск», а установку — с вставки диска в привод или запуска браузера для скачивания дистрибутива. Таким образом, даже описание использования программы «Калькулятор Windows» займёт два десятка страниц.
2. Опытному пользователю требуется изложить все возможности программы с достаточным для понимания уровнем пояснения. Скриншоты по мере необходимости без дополнительных надписей. Вы описываете только работу с программой, ничего сопутствующего — вставить диск или сохранить файл стандартным способом эта ЦА способна самостоятельно.
3. Администратору нужно изложить настройки, описать типовые действия (установку, заведение пользователей и т. д.), максимально кратко, как можно больше использовать списки с перечислением и краткие инструкции. Скриншотами снабжать имеет смысл только наиболее сложные моменты в инструкции. Про непосредственное использование ПО в таком документе можно вообще ничего не писать, для этого есть руководство пользователя.
4. Разработчику не надо вообще ничего описывать, от вас не будет никаких лишних слов. Просто констатация фактов в виде «сущность — определение». Рисунков, кроме блок-схем алгоритмов или схем БД, тут нет вообще. Сделанное подобным образом описание, к примеру, базы данных с сотней таблиц, может занять всего 50-60 страниц.