Представленный образец спецификации стиля документации соответствует требованиям 8.2 и по умолчанию может быть использован в плане документирования.
Примечание — Перед окончательным принятием данной спецификации полезно создать на ее основе модель документа.
В таблице Н.1 приведены элементы стиля и их рекомендуемые значения по умолчанию.
Таблица Н.1 — Элементы стиля и их значения
| Язык | Английский |
|---|---|
| Орфографический словарь | Словарь Маквайра |
| Руководство по грамматике и использованию стиля | «Руководство по стилю для авторов, редакторов и издателей» Австралийское государственное издательство |
| Формат бумаги | A4 |
| Ориентация | Книжная (вертикальная) |
| Вид печати | Двусторонняя |
| Разрешающая способность типографской или лазерной печати | Минимум 300 точек/дюйм |
| Ширина внутреннего поля | 10 мм/2,4 цицеро[2] |
| Ширина внешнего поля | 10 мм/2,4 цицеро[2] |
| Цвет краски | Черный |
| Цвет, масса и вид бумаги | Белая, 80 г/см², матовая |
| Разделители | Нет |
| Переплет | Пластиковый комбинированный, с прозрачной верхней и черной нижней обложками, плотностью 200–260 г/см² |
| Метод воспроизведения и качество | Все материалы должны быть пригодными к фотокопированию и не иметь помарок и обесцвечиваний |
| Схема нумерации страниц | Страницы нумеруют в формате 1, 2, 3 и т. д., начиная с первой после обложки |
| Нумерация таблиц и рисунков | Рисунки нумеруют в формате «Рисунок 1», «Рисунок 2» и т. д., в порядке их появления в тексте документа. Таблицы нумеруют в формате «Таблица 1», «Таблица 2» и т. д., в порядке их появления в тексте документа |
| Число колонок | Одна |
| Сноски или концевые примечания | Не используют |
| Правила пагинации | Заголовки не должны попадать в конец страницы. Таблицы объемом менее страницы должны размещаться на одной странице. Каждый заголовок первого уровня должен располагаться вверху правой страницы |
| Правила плотности документа | Взаимосвязанные материалы следует размещать на одной странице или на ее обороте. Следует по возможности избегать использования подчеркивания, больших кусков, набранных жирным шрифтом, и текстов, целиком набранных заглавными буквами. Материалы должны занимать от 40 % до 60 % общего объема страницы |
| Вводные и вспомогательные материалы: | |
| - титульный лист | На титульном листе должно быть указано наименование продукции, ее версия, дата выпуска документа и название данного тома |
| - информация о гарантиях, авторских правах и торговой марке | Не приводится |
| - содержание | В содержании должны быть приведены заголовки всех частей, глав и разделов с указанием номеров страниц |
| - список рисунков и таблиц | Не приводится |
| - приложения | Не предусмотрены |
| - глоссарий | В глоссарии должен быть определен любой термин, неизвестный аудитории пользователей документа, в терминах, знакомых данной аудитории |
| - перечни обозначений и сокращений | Следует указать все встречающиеся в тексте обозначения и сокращения. Если данные элементы не являются очевидными по смыслу, они должны быть пояснены соответствующим текстом |
| - указатель | В соответствии с Н.3 |
| - порядок | Располагаются в порядке их перечисления в настоящей таблице, основная часть документа располагается между содержанием и глоссарием |
| Гарнитуры шрифтов и кегли текста основной части документа | Times Roman, 12 п |
| Отступы по горизонтали и пробелы по вертикали в тексте основной части | Текст основной части должен иметь общий отступ на 2 п и левосторонний отступ на 30 мм/7 цицеро. Между абзацами должен быть вертикальный пробел в одну строку |
| Выравнивание текста основной части | Текст основной части должен быть выровнен по левой стороне с неровностями по правому краю |
| Количество уровней и наименования заголовков | Четыре; заголовки части, главы, раздела и подраздела |
| Стиль текста заголовков | Все заголовки должны быть изложены в повествовательном стиле с заглавной буквы и без точки в конце |
| Гарнитуры шрифтов, кегли и отступы для каждого уровня заголовков | Все заголовки оформляют шрифтом Times Roman следующими кеглями: заголовок части — 36 п, главы — 24 п, раздела — 18 п, подраздела — 14 п. Заголовки должны быть выровнены по левому краю. Вверху каждого заголовка должен быть пробел, равный двум кеглям данного заголовка, за исключением расположения заголовка вверху страницы. Внизу каждого заголовка должен быть пробел, равный кеглю данного заголовка |
| Графические элементы, используемые в заголовках | Не используются |
| Колонтитулы: | |
| - верхние | Содержат название главы и раздела. Название главы располагают со стороны переплета |
| - нижние | Содержат номер страницы со стороны, противоположной переплету, с указанием на противоположной стороне номера версии, даты ее выпуска и наименования документа |
| Гарнитуры шрифтов, кегли и расположение колонтитулов: | |
| - верхний | Times Roman, кегль 12 п, колонтитулы расположены вверху каждой страницы за исключением титульного листа |
| - нижний | Times Roman, кегль 12 п, номер страницы кегль 12 п, колонтитулы расположены внизу каждой страницы за исключением титульного листа |
| Графические элементы колонтитулов: | |
| - верхний | Должен быть подчеркнут линией толщиной в 1 п с вертикальным пробелом в 1 п |
| - нижний | Должен быть надчеркнут линией толщиной в 1 п с вертикальным интервалом в 1 п |
| Надпись | Начинается с номера рисунка с двоеточием и текстом, например «Рисунок 1:…» |
| Гарнитуры шрифта, кегль и расположение надписей | Times Roman italics, кегль 10 п. Надписи должны быть расположены под рисунком |
| Таблицы | Ширина таблиц должна соответствовать формату текста основной части документа, а для их обрамления используют линии толщиной в 1 п |
| Гарнитуры шрифтов и минимальные кегли для таблиц | Times Roman, минимальный кегль в 8 п |
| Отчеты (сообщения) | Должны содержать правдоподобные (но не фактические) данные |
| Гарнитуры шрифтов и минимальные кегли для отчетов | Courier, минимальный кегль в 8 п |
| Компоновка отчетов | Должны быть представлены в горизонтальной (альбомной) компоновке без использования страниц-раскладок |
| Распечатки экранов: | |
| - содержание | В каждом поле распечаток экранов должны быть представлены правдоподобные (но не фактические) данные |
| - оформление | Не должно быть горизонтальных или вертикальных искажений. Их ширина должна соответствовать формату набора |
| - частичные (т. е. представляющие часть экрана) | Должны быть в масштабе полноэкранных распечаток |
| Минимальная толщина линий, гарнитуры шрифтов и кегли для рисунков | 0,5 п, шрифт Times Roman, минимальный кегль в 8 п |
| Рисунки | Рисунки и текст внутри них должны располагаться соответственно тексту основной части документа |
| Стиль текста уведомлений и предостережений | Стиль повествовательный, начинается со слова «Внимание:» или «Осторожно:» |
| Гарнитуры шрифтов, кегли и отступы для уведомлений и предостережений | Times Roman, кегль 24 п, расположение — по центру страницы, пробелы сверху и снизу, интервалы сверху и снизу — равные двум строкам |
| Справочный текст | Должны быть обеспечены возможности создания контекстных и расширенных справок, справок о клавишах, справок о справках и терминологических справок |
| Диалоговая документация | Должна содержать руководства для пользователя, командные справки, рекомендации по сообщениям и административную информацию |
| Сопутствующие материалы | Информация по одной тематике по возможности должна располагаться на одном экране |
| Подсветка и использование цвета | Цветовое оформление в диалоговой документации и справочных текстах не используют. Подсветку (более яркую цветовую тональность) используют только для заголовков |
| Диалоговая документация и справочный текст | Вверху отображаемого текста оставляют пустую строку (то есть между заголовком или верхом экрана и первой строкой текста). Формат текста — одноколонный |
| Заголовки диалоговой документации и справочного текста | Заголовки подсвечивают, используя более яркую цветовую тональность. Применяют только два уровня заголовков. Заголовки излагают в повествовательном стиле (см. 8.2.3.7.2). Сверху и снизу каждого заголовка оставляют пробел, равный одной строке |
| Текст основной части электронной документации | Должен быть выровнен по левой стороне, допускаются неровности по правому краю. Слева от каждой строки текста оставляют пробел, равный 20 символам |
| Правила навигации | Уровни расположения взаимосвязанной информации должны быть организованы и контролироваться так, чтобы пользователи могли легко возвращаться в исходную точку (пункт), содержание или указатель без блуждания в тексте документа |
| Клавиатура | Должны быть использованы следующие клавиши: F1 — для вызова справочной системы: Alt-Fl или Esc — для выхода из справочной системы. Никакие данные, введенные пользователем ранее, не должны быть потеряны при возврате из справочной системы к основному экрану |
Каждый документ, содержащий более 32 страниц, должен иметь указатель.
Примечание — Указатель должен охватывать все компоненты документа, включая вводные материалы, приложения, дополнения и рисунки.
Указатель должен быть достаточно подробным, чтобы удовлетворить потребностям соответствующих аудиторий.
Примечание — Указатель должен занимать от 5 % (для учебных руководств) до 10 % (для справочных руководств) общего объема данного документа. Следует рассмотреть возможность использования профессиональных классификаторов.
Весь комплект документации должен иметь единый указатель, если иное не оговорено в плане документирования.
Примечания
1 В качестве заголовков (элементов) указателя (слов или фраз, вносимых в указатель) следует использовать объекты, выбранные из конкретного документа (например, «программное средство»).
2 Для представления одинакового понятия должен использоваться один и тот же термин.
3 В указателе могут быть использованы подзаголовки, описывающие некоторые аспекты основного заголовка.
4 Заголовки указателя должны представлять основные понятия из конкретного документа. Для них следует использовать имена существительные, при необходимости дополняя их прилагательными, другими существительными или глаголами. В качестве заголовков могут быть взяты машинные команды, использованные в документации и представленные в виде глагола.
5 Термины, состоящие из нескольких слов, следует применять как заголовки без разбивки их на подзаголовки.
6 Следует избегать использования предлогов, если их отсутствие не приводит к неоднозначному пониманию термина.
7 Понятия, отражающие различные аспекты одного объекта, должны быть перечислены как подзаголовки основного заголовка указателя.
8 Сокращения и обозначения должны быть расположены а алфавитном порядке (например, обозначение «BASIC» для «Beginner's All-purpose Symbolic Instruction Code» между «Base» и «Battery»).
9 Заголовки указателя должны располагаться в алфавитном порядке, пробел должен трактоваться как символ, предшествующий последующему (например, термин «Alt key» размещается перед «Alternative»).
Для каждого элемента (заголовка, подзаголовка) указателя должны быть даны локальные ссылки при отсутствии перекрестных ссылок.
В справочных ссылках должен быть указан либо номер страницы документа (например, 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).
В перекрестных ссылках на сокращения, синонимы или альтернативные виды термина, выбранные из элементов указателя, следует использовать сокращение «См.» (например, проект — см. оформление).
Примечание- Дополнительно перекрестная ссылка с сокращением «См.» может быть дана на другие элементы документа. За перекрестной ссылкой не следует использовать локальную ссылку.
Перекрестная ссылка со словами «См. также» может быть дана из более обширного термина на менее исчерпывающие термины, если не используется прямая локальная ссылка.
Примечание — Перекрестные ссылки со словами «См. также» следует использовать для взаимоувязки терминов в интересах пользователя. Перекрестная ссылка со словами «См. также» под основным элементом указателя должна объединять ряд связанных элементов указателя, имеющих справочные ссылки. Например Рисунки 4
см. также графические элементы; распечатки экранов
индексирование 12
список 15
нумерация 2 Слова «См.» и «См. также» обычно выделяют курсивом.
Цицеро — шрифт, кегль которого равен 12 п (~ 4,51 мм).
Цицеро — шрифт, кегль которого равен 12 п (~ 4,51 мм).