Указатель должен быть достаточно подробным, чтобы удовлетворить потребностям соответствующих аудиторий.
Примечание — Указатель должен занимать от 5 % (для учебных руководств) до 10 % (для справочных руководств) общего объема данного документа. Следует рассмотреть возможность использования профессиональных классификаторов.
Н.3.3 Состав (содержание) и организация указателя
Весь комплект документации должен иметь единый указатель, если иное не оговорено в плане документирования.
Примечания
1 В качестве заголовков (элементов) указателя (слов или фраз, вносимых в указатель) следует использовать объекты, выбранные из конкретного документа (например, «программное средство»).
2 Для представления одинакового понятия должен использоваться один и тот же термин.
3 В указателе могут быть использованы подзаголовки, описывающие некоторые аспекты основного заголовка.
4 Заголовки указателя должны представлять основные понятия из конкретного документа. Для них следует использовать имена существительные, при необходимости дополняя их прилагательными, другими существительными или глаголами. В качестве заголовков могут быть взяты машинные команды, использованные в документации и представленные в виде глагола.
5 Термины, состоящие из нескольких слов, следует применять как заголовки без разбивки их на подзаголовки.
6 Следует избегать использования предлогов, если их отсутствие не приводит к неоднозначному пониманию термина.
7 Понятия, отражающие различные аспекты одного объекта, должны быть перечислены как подзаголовки основного заголовка указателя.
8 Сокращения и обозначения должны быть расположены а алфавитном порядке (например, обозначение «BASIC» для «Beginner's All-purpose Symbolic Instruction Code» между «Base» и «Battery»).
9 Заголовки указателя должны располагаться в алфавитном порядке, пробел должен трактоваться как символ, предшествующий последующему (например, термин «Alt key» размещается перед «Alternative»).
Н.3.4 Справочные ссылки
Для каждого элемента (заголовка, подзаголовка) указателя должны быть даны локальные ссылки при отсутствии перекрестных ссылок.
В справочных ссылках должен быть указан либо номер страницы документа (например, 1, 2), либо номера раздела, подраздела и т. д. (например, «2.22», «3.34»). При указании рисунков справочные ссылки могут быть даны на их номера.
Примечания
1 Обычно пользователям удобнее пользоваться ссылками на страницы, чем на разделы документа.
2 Для элементов указателя не следует использовать большие перечни локальных ссылок. Максимально удобными для работы являются пять ссылок (например, 1, 33, 43, 99, 102). Во избежание длинных перечней локальных ссылок следует использовать подзаголовки.
3 Ссылки, подлежащие обсуждению, могут быть выделены шрифтом (гарнитурой, кеглем).
4 Если перечень подзаголовков охватывает несколько колонок (столбцов), вверху каждой колонки должно быть указано наименование основного заголовка со словом «продолжение».
5 Если используют особую последовательность нумерации страниц, она должна быть указана в указателе. Например, если нумерация начинается с номера каждой главы, данный номер должен быть указан в локальной ссылке, то есть «2-22, 3-34».
6 Если элемент указателя используют в нескольких частях документа, нумеруемых последовательно, в локальной ссылке должны быть указаны только первые и последние номера, разделенные тире (например, 3 — 11). Когда тире используют в нумерации страниц, для разделения страниц тире не используется (например, 3–6 до 3–8).
Н.3.5 Перекрестные ссылки
В перекрестных ссылках на сокращения, синонимы или альтернативные виды термина, выбранные из элементов указателя, следует использовать сокращение «См.» (например, проект — см. оформление).
Примечание- Дополнительно перекрестная ссылка с сокращением «См.» может быть дана на другие элементы документа. За перекрестной ссылкой не следует использовать локальную ссылку.
Перекрестная ссылка со словами «См. также» может быть дана из более обширного термина на менее исчерпывающие термины, если не используется прямая локальная ссылка.
Примечание — Перекрестные ссылки со словами «См. также» следует использовать для взаимоувязки терминов в интересах пользователя. Перекрестная ссылка со словами «См. также» под основным элементом указателя должна объединять ряд связанных элементов указателя, имеющих справочные ссылки. Например Рисунки 4
индексирование 12
список 15
нумерация 2 Слова «См.» и «См. также» обычно выделяют курсивом.
Библиография
В нижеперечисленных публикациях содержится более подробная информация по некоторым темам, связанным с настоящим стандартом.
[1] ИСО/МЭК 6592–2000[3] Информационная технология. Руководство по документированию прикладных автоматизированных систем
[2] BS 7649-93 Руководство по проектированию и выпуску документации пользователей прикладных программных средств
[3] Barnum C. M. and Capliner S. Techniques for Technical Communicators, MacMillan, 1993
[4] Brockmann R. J. Writing Better Computer User Documentation, Wiley, 1990
[5] Brusaw C. T., Alred G. J. and Oliu W. E. Handbook of Technical Writing, St. Martin's Press, 1993
[6] Burnett R. E. Technical Communications, Wadsworth Publishing, 1994
[7] Hackos J. T. Managing Your Documentation Projects, Wiley, 1994
[8] Holtz H. The Complete Guide to Writing Readable User Manuals. Dow Jones-Irwin, 1988
