Оформление пользовательской документации
TBD
Требования к оформлению документации пользователя
1. Введение
Данный документ содержит требования по оформлению документации пользователя. Назначение этого документа предоставить набор правил, позволяющих формировать правильно структурированные и оформленные эксплуатационные документы, а также обеспечить соблюдения единого стиля. Также требования настоящего документа могут частично применяться к оформлению функциональных требований.
2. Предмет документирования
Разработка технической документации подразумевает четкое выделение предмета документирования и его границ. Предметом документирования может быть, например, программа или программный комплекс, определенная комплектация поставки программного комплекса, платформа для разработки программ или систем определенного типа и т.п.
У предмета документирования должны быть четкие обозначения, в том числе:
· официальное полное наименование;
· номер версии, дата выпуска или другие данные, идентифицирующие конкретное состояние предмета документирования, которое будет зафиксировано в документации.
3. Комплект документации. Документ
Техническая документация реализуется в форме комплекта, состоящего из определенных документов.
Каждый документ имеет свой собственный предмет, который может совпадать с предметом документирования в целом или представляет собой часть предмета документирования (модуль, компонент и т. п.).
При написании любого документа принимаются во внимание характеристики его типичного читателя, в первую очередь:
- квалификация в предметной области;
- квалификация в области информационных технологий;
- состав задач, решаемых с помощью предмета документирования;
- предоставленные читателю права доступа к тем или иным данным, функциям, объектам.
Типичные читатели документа составляют его целевую аудиторию. Предполагается, что целевая аудитория документа едина по перечисленным характеристикам. Каждый документ должен содержать информацию, необходимую его целевой аудитории для решения поставленных перед ней задач. При этом информация в документе должна быть представлена в форме, наиболее удобной этой целевой аудитории.
Если персонал, работающий с программным продуктом, достаточно разнороден, необходимо выделять несколько целевых аудиторий (пользователи, специалисты по сопровождению, администраторы и др.), для каждой из которых разрабатывается свой набор документов.
Документы бывают разных типов (жанров, разновидностей), в зависимости от характера представленных в них сведений и порядка изложения последних. Например: руководство пользователя, руководство администратора, руководство программиста, описание применения и т. д.
При разработке документа принимается решение о том, с какой подробностью в нем будут изложены сведения: максимально полно или избирательно. Решение об избирательном изложении сведений связано главным образом с характеристиками целевой аудитории.
Основными характеристиками документа являются:
- предмет документа;
- тип документа;
- подробность изложения.
Тип документа определяется необходимостью предоставления читателю тех или иных сведений для успешной эксплуатации предмета. Подробность изложения сведений в документе определяется способом адаптации документа к нуждам целевой аудитории.
Документ должен иметь название. В названии документа должны упоминаться его предмет и тип, например: «Утилиты для работы с диском. Руководство пользователя», «Утилиты для работы с диском. Руководство по установке».
Заголовок документа оформляется титульным листом (если это предусмотрено типом документа - для пользовательских инструкций по операциям - не оформляется).
Если документ утверждается, в правом верхнем углу указывается слово «УТВЕРЖДЕНО», под ним должность, Ф.И.О утвердившего лица, дата утверждения и место для подписи.
Посередине листа с центрированием по центру указывается название документа.
Чуть ниже указывается подразделение (или подрядчик), разработавшее документ и Ф.И.О. автора или сотрудника ответственного за организацию разработки документации.
Внизу титульного листа по центру указывается Город и ниже месяц и год разработки.
4. Формальная структура документа
Документ делится на структурные элементы разного уровня: разделы, подразделы, пункты, подпункты и т. д. Каждому структурному элементу должен быть присвоен заголовок. Текст, не разделенный на структурные элементы, называется сплошным.
Состав разделов и порядок их следования, как правило, определяется типом документа и может быть взят из применяемого стандарта. Состав структурных элементов следующих уровней определяется содержательными соображениями, в частности, правилами расположения информации разного типа (см. ниже).
На количество разделов в документе ограничений не накладывается. Количество подразделов внутри раздела, пунктов внутри подраздела и т. д. рекомендуется ограничить девятью. Глубину вложенности структурных элементов рекомендуется ограничить четырьмя (т. е. избегать деления подпунктов на более мелкие структурные элементы).
Документ, содержащий более 5-ти разделов и/или более 5 страниц, должен включать оглавление.
5. Типы информации в документе
Информация, излагаемая в документе, может быть разделена на три типа:
- структурная;
- процедурно-функциональная;
- справочная.
Структурная информация касается понятийного аппарата предметной области и предмета документирования, рассматриваемых в документе явлений и взаимосвязей между ними.
Процедурно-функциональная информация касается решения пользовательских задач и применения пользователем функциональных возможностей программного продукта.
Справочная информация — это всевозможные вспомогательные сведения о функциях, параметрах, режимах работы и т.п.
Информацию разных типов рекомендуется располагать в следующем порядке: сначала структурная информация, затем процедурно-функциональная и в заключение справочная. Эта рекомендация относится и к документу в целом (на уровне разделов, подразделов и т.д.), и к отдельным его частям (на уровне сплошного текста).
Наибольший объем текста в документе обычно приходится на процедурно-функциональную информацию. Структурная и справочная информация при всей их важности носят вспомогательный характер: структурная информация предваряет, а справочная уточняет процедурно-функциональную.
Следует уже при составлении структуры документа принять решение о том, какой общий принцип будет лежать в основе изложения сведений — процедурный или функциональный. Выбор общего принципа осуществляется не произвольно, а на основании существенных соображений. Если в документе описывается решение ряда конкретных пользовательских задач, и для каждой задачи излагается пошаговый порядок ее решения, лучше работает процедурный принцип. Если состав задач пользователя заранее неизвестен, в документе приходится описывать отдельные функциональные возможности и способы их применения в различных ситуациях. Тогда удобнее функциональный принцип.
Выбрав один из принципов изложения сведений, необходимо последовательно придерживаться его. Исключения допускаются при написании тех разделов, для которых выбранный принцип не подходит. Главным образом, речь идет о написании разделов, посвященных настройке, конфигурированию и обслуживанию программы, — для этих разделов всегда предпочтителен функциональный принцип.
6. Изложение материала в сплошном тексте
Абзацы и предложения
Сплошной текст должен быть разбит на хорошо обозримые абзацы. Рекомендуется, чтобы размер большинства абзацев не превышал одну восьмую страницы. Также рекомендуется воздерживаться от написания длинных и синтаксически сложных предложений. Если удается разделить предложение на два других, не сделав хотя бы одно их них противоестественно коротким, то в общем случае лучше заменить его двумя логически связанными предложениями.
Перечисления. Маркированные и нумерованные списки
Перечисление компонентов, функций, возможностей, любых других однородных объектов или категорий следует оформлять в виде списка. Если пункты перечисления объективно не упорядочены, следует использовать маркированный список. Если пункты перечисления объективно образуют последовательность, следует использовать нумерованный список с численной нумерацией. Если пункты перечисления объективно не упорядочены, но необходимо на них ссылаться из текста, можно использовать нумерованный список с буквенной нумерацией.
Перерастание списка в таблицу
Если все пункты списка относительно объемны и имеют одинаковую структуру, рекомендуется оформить перечисление не списком, а таблицей.
Таблиц должны иметь наименование или номер. Ссылки на таблицы в документе должны быть кликабельными.
Изложение структурной информации
Структурная информация должна формировать у читателя системное представление обо всех понятиях, явлениях и взаимосвязях, на которые опирается изложение процедурно-функциональной и справочной информации. Однако нет необходимости явно вводить понятия, явления и взаимосвязи, заведомо знакомые целевой аудитории в силу ее квалификации или бытового опыта.
Структурная информация должна излагаться в следующем порядке: от заведомо известного читателю к неизвестному. Каждое следующее понятие должно раскрываться через заведомо известные читателю или ранее введенные в тексте понятия. Системные взаимосвязи желательно описывать только после того, как все участвующие в них объекты или явления будут представлены читателю.
Структурная информация не должна быть избыточной. Не надо вводить и разъяснять понятия, которые в дальнейшем не используются. Не надо сообщать о явлениях больше, чем необходимо целевой аудитории для решения поставленных перед ней задач.
Изложение процедурно-функциональной информации
Процедурная информация
Под процедурной информацией подразумевается описание действий пользователя по решению определенной пользовательской задачи. Процедурная информация обычно излагается в предположении, что пользователь решает с помощью программы обозримое число пользовательских задач и для каждой задачи нуждается в пошаговом описании ее решения.
Каждую пользовательскую задачу рекомендуется описывать по следующему плану:
Постановка пользовательской задачи. Описание достигаемого результата (например, набора выходных данных) и его смысла с точки зрения пользователя, описание входных данных и начальных условий, предупреждения о возможных неожиданных или негативных последствиях (если они возможны).
Пошаговое описание процедуры решения пользовательской задачи. Каждый шаг, совершаемый пользователем, оформляется в виде пункта нумерованного списка. В отдельный шаг процедуры рекомендуется включать непрерывные во времени действия пользователя, вызывающие значимую реакцию системы, например, выбор некоторого пункта меню, заполнение и оправка формы, нажатие комбинации «горячих» клавиш и т. п. Описание каждого шага должно в общем случае состоять из следующих частей:
- описание как таковых действий пользователя (обязательно);
- описание реакции системы в случае успеха (обязательно);
- описание возможных ошибок и способов их устранения (если есть).
При описании действий пользователя изложение должно идти на уровне конкретных элементов интерфейса, однозначно идентифицируемых пользователем по заголовкам или внешнему виду: экранных форм, полей, кнопок, пиктограмм, пунктов меню и т.п.
Дополнительные сведения: рассмотрение второстепенных вариантов выполнения процедуры в случае ее ветвления, справочные таблицы и т. п.
Функциональная информация
Под функциональной информацией подразумевается описание функциональных возможностей программы. Функциональная информация обычно излагается в предположении, что пользователь самостоятельно формулирует задачи и, владея функциональной информацией, в состоянии найти пути их решения.
Каждую функциональную возможность рекомендуется описывать по следующему плану:
- Наименование функциональной возможности.
- Элемент пользовательского интерфейса, предоставляющий доступ к функциональной возможности.
- Указания по применению функциональной возможности (могут быть изложены в форме краткой процедуры).
- Описания взаимосвязанных или однотипных функциональных возможностей рекомендуется собирать в таблицу, где каждой функциональной возможности отведена одна строка. Каждый столбец таблицы соответствует пункту приведенного выше плана описания.
Изложение справочной информации
Справочную информацию рекомендуется излагать в форме, которая обеспечивает читателю наибольшее удобство при поиске нужных сведений. Часто такой формой оказывается таблица.
Расположение информации разных типов в сплошном тексте
Структурную информацию рекомендуется выносить в начало сплошного текста, чтобы ввести читателя в курс дела до того, как он начнет действовать.
Допускается включать в описание шага процедуры обозримые блоки функциональной информации. Например, описание шага, который заключается в заполнении формы, можно сопроводить таблицей, описывающей ее отдельные поля.
Справочную информацию рекомендуется выносить в конец сплошного текста, а при значительном объеме в отдельные структурные элементы в конце документа, например в приложения.
7. Слова и формулировки
Словарь документации пользователя должен быть жестко ограничен рамками решаемой задачи. Следует обратить внимание на следующие группы слов.
Терминология. Терминология — как компьютерная, так и относящаяся к предметной области — должна употребляться во всей документации единым образом: термин не может употребляться в различных значениях, а два термина не могут употребляться в одном и том же значении.
Вспомогательная терминология. Сюда относятся разного рода отвлеченные слова, не являющиеся собственно терминами, но служащие для описания работы программ и действий пользователя, например: открывать (что-либо для редактирования), протекать (о процессе), редактировать (о данных) и т.д. Сюда же относятся обобщающие слова для программных продуктов, групп персонала, объектов обработки и т.д. Следует использовать в одинаковых (сходных) ситуациях одинаковые (сходные) слова и выражения.
Слова-«артикли». Слова вроде «соответствующий», «данный», «вышеупомянутый» и другие, используемые для указания и уточнения, не рекомендуются к употреблению и используются только в случае крайней необходимости, поскольку они только загромождают текст. Следует использовать прямые и конкретные указания на объекты и функции — по имени или другому идентификатору.
Формулировки, используемые в документации, должны отвечать следующим требованиям.
Строгость. Следует использовать только терминологические, а не расплывчатые общие именования, употреблять технически грамотные выражения, не допускать высказываний слишком узких или слишком широких по смыслу.
Лаконичность. Следует стремиться высказывать мысль с употреблением минимума лишних слов.
Завершенность. Следует проговаривать все аспекты той или иной ситуации, а не рассчитывать на догадливость пользователя. Например, не «передача в другой формат», а «передача данных из внутреннего формата программы в другой формат».
Однозначность. Следует использовать выражения, не допускающих многозначных толкований. Особое внимание следует обратить внимание на употребление модальных глаголов и слов «мочь», «хотеть», «быть должным», «быть необходимым» и проверять себя — всегда ли пользователь правильно понимает их смысл.
Единство стиля. Все тезисы разрабатываемого документа должны строиться в единой стилистике, действия, которые должен выполнять пользователь должны формулироваться в повелительном или побудительном виде («необходимо нажать», «нажмите»); действия автоматизированных систем в простом настоящем времени или в виде предоставления пользователю возможности («система выводит», «система предоставляет возможность …»).
8. Изображения и иллюстрации
Используемые в документации иллюстрации, на которые в тексте есть ссылки должны иметь наименование или номер. Ссылки на иллюстрации должны быть кликабельными.
Изображения в тексте не несущие смысловой нагрузки и предназначенные для выделения текста или обращения внимания читателя на текст могут не именоваться. Такие изображения рекомендуется оформлять в едином стиле по всему документу.
9. Оформление
В качестве основного стиля текста используется Times New Roman 13, невыделенный.
Для заголовков допустимо выделение жирным, выделение цветом (темно-синий), увеличение размера шрифта до 14, 15, 16.
Абзацы основного текста выравниваются по ширине. Отступ слева 0, отступ справа 0, отступ первой строки 1,5 см.
Расстояние между строками рекомендуется с множителем 1,15.
Интервалы перед и после абзаца – определяются эстетическими соображениями, но не могут превышать 30 пт.
Расстояние между строками и интервал после абзаца могут быть изменены, если необходимо уместить текст в страницу или, напротив, перенести больший блок текста на другую страницу. При этом межстрочное расстояние и интервал после абзаца должны меняться на всей странице.
Следует разделять употребление символов дефисов «-» и тире «–». Для вставки тире используется комбинация клавиш Ctrl-«-» на цифровой клавиатуре.
Сокращения в тексте документа используются, только если они были ранее введены в отдельном параграфе документа или по тексту. Введение сокращения по тексту осуществляется в скобках после указания сокращаемого слова или словосочетания следующим образом «(далее – Сокращение)». Сокращения должны выбираться так, чтобы их нельзя было перепутать с другими словами. Обычно сокращение целесообразно писать с заглавной буквы. Аббревиатуры пишутся целиком заглавными буквами.
Фамилия, имя, отчество указывается в документе либо полностью в этой же последовательности, либо сокращенно в виде «Фамилия И.О.», причем между фамилией и «И.О.» ставится неразрывный пробел
ООО "Ромашка" пишется с неразрывными пробелами между «ООО» и знаком кавычки (чтобы не переносилось на другую строку отдельно). Неразрывный пробел вводится комбинацией клавиш Ctrl-Shift-Пробел.
Даты в документа могут указываться в следующих форматах:
- 01.01.2001 («г.» НЕ ставится);
- 1 января 2001 года;
- «01» января 2001 г. (между годом и «г.» ставится неразрывный пробел).
При наличии в инструкции более 1 страницы, все страницы нумеруются в нижнем колонтитуле с выравниванием по середине страницы.
10. Авторская разметка текста
В тексте технической документации на программы принято оформлять врезками, выделяемыми рамкой, следующие сведения:
- предупреждения о неочевидных или неожиданных последствиях действий пользователя;
- предостережения о возможных негативных последствиях действий пользователя;
- критически важные сведения, пренебрежение которыми может привести к ошибкам;
- полезные дополнительные сведения, например, советы пользователю.
Предупреждения и предостережения обязательно должны располагаться в тексте перед описанием тех действий, к которым они относятся.
В тексте технической документации на программы принято выделять шрифтом следующие фрагменты (Таблица 1. Выделенный текст).
Таблица 1. Выделенный текст
| Тип выделенного текста | Принятый способ выделения |
| вводимые термины | курсив |
| наименования элементов интерфейса | полужирный шрифт |
| обозначения клавиш и их комбинаций | полужирный шрифт, ПРОПИСНЫЕ буквы |
| строки, вводимые пользователем с клавиатуры, значения и другие литералы | моноширинный шрифт, например
Courier New |
