ГОССТАНДАРТ РОССИИ - Информационная технология ПРОЦЕСС СОЗДАНИЯ ДОКУМЕНТАЦИИ ПОЛЬЗОВАТЕЛЯ ПРОГРАММНОГО СРЕДСТВА

• Название: Информационная технология ПРОЦЕСС СОЗДАНИЯ ДОКУМЕНТАЦИИ ПОЛЬЗОВАТЕЛЯ ПРОГРАММНОГО СРЕДСТВА
• Автор: ГОССТАНДАРТ РОССИИ
• Издательство: ИПК Издательство стандартов
• Жанр: Техническая литература
• Год: 2003

Настоящий стандарт содержит полный аутентичный текст международного стандарта ИСО/МЭК 15910-99 «Информационная технология. Процесс создания документации пользователя программного средства»

---

Н.3 Спецификация указателя

Н.3.1 Общие положения

Каждый документ, содержащий более 32 страниц, должен иметь указатель.

Примечание — Указатель должен охватывать все компоненты документа, включая вводные материалы, приложения, дополнения и рисунки.

Н.3.2 Качество

Указатель должен быть достаточно подробным, чтобы удовлетворить потребностям соответствующих аудиторий.

Примечание — Указатель должен занимать от 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

[9] Horton W. K. Illustrating Computer Documentation. Wiley, 1991

[10] Simpson H. and Casey S. M. Developing Effective User Documentation: A Human Factors Approach. МсGraw-Hill, 1988

[11] Weiss E. H. How to Write Usable User Documentation, Oryx Press ‹ 1991

[12] Zinsser W. On Writing Well, Harper and Row ‹ 1994

Диалоговая документация и гипертекст

[13] Bogan S., Farkas D. and Wellinske J. Developing On-Line Help for Windows, International Thomson Press, 1995

[14] Brown C. M. Human-Computer Interface Design. Norwood, 1988

[15] Helander (Ed). Handbook of Human-Computer Interaction. North Holland

[16] Horton W. K. Designing and Writing On-line Documentation. Help Text to Hypertext. Wiley, 1990

[17] Horton W. K. Designing and Writing On-line Documentation: Hypermedia for Self-Supporting Products, Wiley,

[18] Laurel and Mountford, The Art of Human-Computer Interface Design. Addison-Wesley, 1990 [19] Van Der Veer and Mulder, Human-Computer Interaction. Springer-Verlag, 1988

Тестирование на практичность

[20] Dumas J. S. and Redish J. С A Practical Guide to Usability Testing, Ablex Publishing, 1993 [21] Nielson J. Usability Engineering, AP Professional, 1993

Тематический указатель

авторские права

    в плане документирования… 8.1.3.1g

    в образце плана… С.7

    обязанности заказчика… 8.1

    при оценке плана документирования… приложение G

    формулировка… 8.2.3.5b

активный разделитель, определение… 4.54

алфавитный порядок в указателе… Н.3.3

альбомная (горизонтальная) ориентация… 8.2.3.1.2,8.2.3.11.4

анализ требований… 8.1.3

Аудитория

    доступ… 8.1.2d

    изучение… 4.4, В.1

    образец плана… С.4

    описание… 8.1.3.1,8.1.3.2, приложение G

    определение… 4.3

библиография… библиография

    описание для перевода… приложение Е

бумага… 8.2.3.1.8

    размер (формат)… 8.2.3.1.1

бумажная документация… 8.2.3

    определение… 4.34

вводный материал

    определение… 4.21

    спецификация… 8.2.3.5

верхний колонтитул… 4.22

взаимодействие между заказчиком и документатором… 8.1.4.1

вопросы законности… 8.1.4.1

Время

    необходимое… 8.1.3.1

    оценка… приложение F

вспомогательный материал

    определение… 4.6

    спецификация… 8.2.3.5

выравнивание текста

    в бумажной документации… 8.2.3.6.4

    в диалоговой документации… 8.2.4.3.6

грамматика… 8.2.2.3

Гранки

    определение… 4.40

    количество копий… В.1b

    проверка… 8.1.4.5

графические элементы

    в диалоговой документации… 8.2.4.3.7

    верхние и нижние колонтитулы… 8.2.3.8

    заголовки… 8.2.3.7

    необходимое время для разработки… F.2

    описание для перевода… Е.4

    уведомления и предостережения… 8.2.3.14

дата пересмотра… 4.8

даты (при переводе)… E.6h

двусторонняя печать… 8.2.3.1.3

    верхние и нижние колонтитулы… 8.2.3.8

диалоговая документация… 8.2.4.2

    в плане документирования… 8.1.3.1

    описание для перевода… Е.5

    определение… 4.31

длина строки… 8.2.3.6.3

Договор

    использование настоящего стандарта… приложение В