Данный документ представляет собой очень сжатый свод правил и советов для разработчиков технической документации. Прежде всего, он относится к документации пользователя программного продукта, хотя некоторые положения могут быть расширены и применены к документации других типов. Перечень затронутых здесь вопросов нельзя назвать исчерпывающим, однако, руководствуясь этим документом, разработчики смогут создавать хотя бы поверхностно правильно структурированные и оформленные эксплуатационные документы, а также добиться соблюдения единого стиля при работе в команде.
Разработка технической документации подразумевает четкое выделение предмета документирования и его границ. Предметом документирования может быть, например, программа или программный комплекс, определенная комплектация поставки программного комплекса, платформа для разработки программ или систем определенного типа и т.п.
У предмета документирования должны быть четкие обозначения, в том числе:
официальное полное наименование;
номер версии, дата выпуска или другие данные, идентифицирующие конкретное состояние предмета документирования, которое будет зафиксировано в документации.
В идеале предмет должен быть защищен от изменений во время документирования. На практике добиться этого обычно не получается. Во всяком случае, процесс документирования должен быть организован таким образом, чтобы любое изменение в предмете оперативно доводилось до сведения разработчика документации.
Техническая документация реализуется в форме комплекта, состоящего из определенных документов.
Каждый документ имеет свой собственный предмет, который может совпадать с предметом документирования в целом или представляет собой часть предмета документирования (модуль, компонент и т. п.).
При написании любого документа принимаются во внимание характеристики его типичного читателя, в первую очередь:
квалификация в предметной области;
квалификация в области информационных технологий;
состав задач, решаемых с помощью предмета документирования;
предоставленные читателю права доступа к тем или иным данным, функциям, объектам.
Типичные читатели документа составляют его целевую аудиторию. Предполагается, что целевая аудитория документа едина по перечисленным характеристикам. Каждый документ должен содержать информацию, необходимую его целевой аудитории для решения поставленных перед ней задач. При этом информация в документе должна быть представлена в форме, наиболее удобной этой целевой аудитории.
Часто оказывается, что персонал, работающий с программным продуктом, достаточно разнороден, так что можно выделить не одну, а несколько целевых аудиторий (пользователи, специалисты по сопровождению, администраторы и др.), для каждой из которых разрабатывается свой набор документов.
Документы бывают разных типов (жанров, разновидностей), в зависимости от характера представленных в них сведений и порядка изложения последних. Известны такие типы документов, как руководство пользователя, руководство администратора, руководство программиста, описание применения и т. д. Распространенные системы стандартов (международных, национальных, отраслевых), а также стандарты, принятые в организациях и на предприятиях, как правило, предусматривают формирование комплекта из разнотипных документов, что позволяет описать предмет документирования всесторонне.
При разработке документа принимается решение о том, с какой подробностью в нем будут изложены сведения: максимально полно или избирательно. Решение об избирательном изложении сведений связано главным образом с характеристиками целевой аудитории.
Итак, основными характеристиками документа являются:
предмет документа;
тип документа;
подробность изложения.
Предмет документа определяется в основном поставленной перед техническим писателем задачей. Тип документа определяется необходимостью предоставления читателю тех или иных сведений для успешной эксплуатации предмета. Подробность изложения сведений в документе определяется способом адаптации документа к нуждам целевой аудитории.
Документ обязательно должен быть озаглавлен. Если форма, в которой это следует делать, не регламентирована используемым стандартом, рекомендуется, чтобы в заголовке документа упоминались его предмет и тип, например: «Утилиты для работы с диском. Руководство пользователя», «Утилиты для работы с диском. Руководство по установке».
Документ делится на структурные элементы разного уровня: разделы, подразделы, пункты, подпункты и т. д. Каждому структурному элементу должен быть присвоен заголовок. Текст, не разделенный на структурные элементы, называется сплошным.
Состав разделов и порядок их следования, как правило, определяется типом документа и может быть взят из применяемого стандарта. Состав структурных элементов следующих уровней определяется содержательными соображениями, в частности, правилами расположения информации разного типа (см. ниже).
На количество разделов в документе ограничений не накладывается. Количество подразделов внутри раздела, пунктов внутри подраздела и т. д. рекомендуется ограничить девятью. Глубину вложенности структурных элементов рекомендуется ограничить четырьмя (т. е. избегать деления подпунктов на более мелкие структурные элементы).
Информация, излагаемая в документе, может быть разделена на три типа:
структурная;
процедурно-функциональная;
справочная.
Структурная информация касается понятийного аппарата предметной области и предмета документирования, рассматриваемых в документе явлений и взаимосвязей между ними.
Процедурно-функциональная информация касается решения пользовательских задач и применения пользователем функциональных возможностей программного продукта.
Справочная информация — это всевозможные вспомогательные сведения о функциях, параметрах, режимах работы и т.п.
Информацию разных типов рекомендуется располагать в следующем порядке: сначала структурная информация, затем процедурно-функциональная и в заключение справочная. Эта рекомендация относится и к документу в целом (на уровне разделов, подразделов и т.д.), и к отдельным его частям (на уровне сплошного текста).
Наибольший объем текста в документе обычно приходится на процедурно-функциональную информацию. Структурная и справочная информация при всей их важности носят вспомогательный характер: структурная информация предваряет, а справочная уточняет процедурно-функциональную.
Следует уже при составлении структуры документа принять решение о том, какой общий принцип будет лежать в основе изложения сведений — процедурный или функциональный. Выбор общего принципа осуществляется не произвольно, а на основании существенных соображений. Если в документе описывается решение ряда конкретных пользовательских задач, и для каждой задачи излагается пошаговый порядок ее решения, лучше работает процедурный принцип. Если состав задач пользователя заранее неизвестен, в документе приходится описывать отдельные функциональные возможности и способы их применения в различных ситуациях. Тогда удобнее функциональный принцип.
Выбрав один из принципов изложения сведений, необходимо последовательно придерживаться его. Исключения допускаются при написании тех разделов, для которых выбранный принцип не подходит. Главным образом, речь идет о написании разделов, посвященных настройке, конфигурированию и обслуживанию программы, — для этих разделов всегда предпочтителен функциональный принцип.
Сплошной текст должен быть разбит на хорошо обозримые абзацы. Рекомендуется, чтобы размер большинства абзацев не превышал одну восьмую страницы. Также рекомендуется воздерживаться от написания длинных и синтаксически сложных предложений. Если удается разделить предложение на два других, не сделав хотя бы одно их них противоестественно коротким, то в общем случае лучше заменить его двумя логически связанными предложениями.
Перечисление компонентов, функций, возможностей, любых других однородных объектов или категорий следует оформлять в виде списка. Если пункты перечисления объективно не упорядочены, следует использовать маркированный список. Если пункты перечисления объективно образуют последовательность, следует использовать нумерованный список с численной нумерацией. Если пункты перечисления объективно не упорядочены, но необходимо на них ссылаться из текста, можно использовать нумерованный список с буквенной нумерацией.
Если оказывается, все пункты списка, во-первых, относительно объемны, и, во-вторых, имеют одинаковую структуру, рекомендуется оформить перечисление не списком, а таблицей.
Структурная информация должна формировать у читателя системное представление обо всех понятиях, явлениях и взаимосвязях, на которые опирается изложение процедурно-функциональной и справочной информации. Однако нет необходимости явно вводить понятия, явления и взаимосвязи, заведомо знакомые целевой аудитории в силу ее квалификации или бытового опыта.
Структурная информация должна излагаться в следующем порядке: от заведомо известного читателю к неизвестному. Каждое следующее понятие должно раскрываться через заведомо известные читателю или ранее введенные в тексте понятия. Системные взаимосвязи желательно описывать только после того, как все участвующие в них объекты или явления будут представлены читателю.
Структурная информация не должна быть избыточной. Не надо вводить и разъяснять понятия, которые в дальнейшем не используются. Не надо сообщать о явлениях больше, чем необходимо целевой аудитории для решения поставленных перед ней задач.
Под процедурной информацией подразумевается описание действий пользователя по решению определенной пользовательской задачи. Процедурная информация обычно излагается в предположении, что пользователь решает с помощью программы обозримое число пользовательских задач и для каждой задачи нуждается в пошаговом описании ее решения.
Каждую пользовательскую задачу рекомендуется описывать по следующему плану:
Постановка пользовательской задачи. Описание достигаемого результата (например, набора выходных данных) и его смысла с точки зрения пользователя, описание входных данных и начальных условий, предупреждения о возможных неожиданных или негативных последствиях (если они возможны).
Пошаговое описание процедуры решения пользовательской задачи. Каждый шаг, совершаемый пользователем, оформляется в виде пункта нумерованного списка. В отдельный шаг процедуры рекомендуется включать непрерывные во времени действия пользователя, вызывающие значимую реакцию системы, например, выбор некоторого пункта меню, заполнение и оправка формы, нажатие комбинации «горячих» клавиш и т. п. Описание каждого шага должно в общем случае состоять из следующих частей:
I) описание как таковых действий пользователя (обязательно);
II) описание реакции системы в случае успеха (обязательно);
III) описание возможных ошибок и способов их устранения (если есть).
При описании действий пользователя изложение должно идти на уровне конкретных элементов интерфейса, однозначно идентифицируемых пользователем по заголовкам или внешнему виду: экранных форм, полей, кнопок, пиктограмм, пунктов меню и т.п.
Дополнительные сведения: рассмотрение второстепенных вариантов выполнения процедуры в случае ее ветвления, справочные таблицы и т. п.
Под функциональной информацией подразумевается описание функциональных возможностей программы. Функциональная информация обычно излагается в предположении, что пользователь самостоятельно формулирует задачи и, владея функциональной информацией, в состоянии найти пути их решения.
Каждую функциональную возможность рекомендуется описывать по следующему плану:
Наименование функциональной возможности.
Элемент пользовательского интерфейса, предоставляющий доступ к функциональной возможности.
Указания по применению функциональной возможности (могут быть изложены в форме краткой процедуры).
Описания взаимосвязанных или однотипных функциональных возможностей рекомендуется собирать в таблицу, где каждой функциональной возможности отведена одна строка. Каждый столбец таблицы соответствует пункту приведенного выше плана описания.
Справочную информацию рекомендуется излагать в форме, которая обеспечивает читателю наибольшее удобство при поиске нужных сведений. Часто такой формой оказывается таблица.
Структурную информацию рекомендуется выносить в начало сплошного текста, чтобы ввести читателя в курс дела до того, как он начнет действовать.
Допускается включать в описание шага процедуры обозримые блоки функциональной информации. Например, описание шага, который заключается в заполнении формы, можно сопроводить таблицей, описывающей ее отдельные поля.
Справочную информацию рекомендуется выносить в конец сплошного текста, а при значительном объеме в отдельные структурные элементы в конце документа, например в приложения.
Словарь документации пользователя должен быть жестко ограничен рамками решаемой задачи. Следует обратить внимание на следующие группы слов.
Терминология. Терминология — как компьютерная, так и относящаяся к предметной области — должна употребляться во всей документации единым образом: термин не может употребляться в различных значениях, а два термина не могут употребляться в одном и том же значении.
Вспомогательная терминология. Сюда относятся разного рода отвлеченные слова, не являющиеся собственно терминами, но служащие для описания работы программ и действий пользователя, например: открывать (что-либо для редактирования), протекать (о процессе), редактировать (о данных) и т.д. Сюда же относятся обобщающие слова для программных продуктов, групп персонала, объектов обработки и т.д. Следует использовать в одинаковых (сходных) ситуациях одинаковые (сходные) слова и выражения.
Слова-«артикли». Слова вроде «соответствующий», «данный», «вышеупомянутый» и другие, используемые для указания и уточнения, не рекомендуются к употреблению и используются только в случае крайней необходимости, поскольку они только загромождают текст. Следует использовать прямые и конкретные указания на объекты и функции — по имени или другому идентификатору.
Формулировки, используемые в документации, должны отвечать следующим требованиям.
Строгость. Следует использовать только терминологические, а не расплывчатые общие именования, употреблять технически грамотные выражения, не допускать высказываний слишком узких или слишком широких по смыслу.
Лаконичность. Следует стремиться высказывать мысль с употреблением минимума лишних слов.
Завершенность. Следует проговаривать все аспекты той или иной ситуации, а не рассчитывать на догадливость пользователя. Например, не «передача в другой формат», а «передача данных из внутреннего формата программы в другой формат».
Однозначность. Следует использовать выражения, не допускающих многозначных толкований. Особое внимание следует обратить внимание на употребление модальных глаголов и слов «мочь», «хотеть», «быть должным», «быть необходимым» и проверять себя — всегда ли пользователь правильно понимает их смысл. Слова и выражения, обозначающие желание, долженствование, запрет, не рекомендуется употреблять в документации пользователя программного продукта, хотя в технологических инструкциях, действующих в конкретной организации, «должен» и «запрещается» вполне допустимы.
Для унификации употребления основной и вспомогательной терминологии, а также для использования отточенных формулировок рекомендуется в каждой организации вести словарь устойчивых формул для описания сходных ситуаций — фигур описания.
В тексте технической документации на программы принято оформлять врезками следующие сведения:
предупреждения о неочевидных или неожиданных последствиях действий пользователя;
предостережения о возможных негативных последствиях действий пользователя;
критически важные сведения, пренебрежение которыми может привести к ошибкам;
полезные дополнительные сведения, например, советы пользователю.
Предупреждения и предостережения обязательно должны располагаться в тексте перед описанием тех действий, к которым они относятся.
В тексте технической документации на программы принято выделять шрифтом следующие фрагменты (табл. 1).
| Тип выделенного текста | Принятый способ выделения |
| вводимые термины | курсив |
| наименования элементов интерфейса | полужирный шрифт |
| обозначения клавиш и их комбинаций | полужирный шрифт, ПРОПИСНЫЕ буквы |
| строки, вводимые пользователем с клавиатуры, значения и другие литералы |
моноширинный
шрифт, например Courier New |