Оформление документации

1. Цель и область действия стандарта Данный стандарт определяет требования к документации компании Gehtsoft. Вся документация, разрабатываемая компанией или по заказу компании с использованием Microsoft Office Word, должна соответствовать данному стандарту. Нарушение требований стандарта допускается только, если это прямо оговорено другим стандартом или соглашением с контрагентом. 2. Формат документации Документация создается в виде документов Microsoft Office Word 2003 на основе фирменных шаблонов компании. 3. Фирменный шаблон Использование шаблонов позволяет сохранять единство стиля и подхода к оформлению документации. Для разработки документации необходимо использовать один из следующих шаблонов: • gs_text_rus.dot - предназначен для документов на русском языке; • gs_text_eng.dot - предназначен для документов на английском языке; • специфический шаблон для типа документа. В шаблонах определено следующее: • свойства документа; • стили; • параметры страницы; • колонтитулы; • обязательные элементы документа. Поля (местозаполнители для данных), существующие в шаблонах, запрещается удалять или изменять вручную. 3.1. Свойства документа Фирменный шаблон переопределяет назначение основных свойств документа (раздел «Свойства» в меню «Файл»). Таблица 1. Назначение свойств документа Свойство Назначение Название Определяет вид документа (например, «Стандарт»). Тема Определяет наименование документа (например, «Правила оформления документации»). Автор Определяет имя, отчество и фамилию автора документа. Руководитель Определяет номер версии документа (например, «1.0»). Учреждение Определяет наименование компании (Gehtsoft). 3.2. Стили При написании документов необходимо использовать фирменные стили. Все фирменные стили начинаются с префикса GSG, в эти стили запрещается вносить какие-либо изменения. При необходимости допускается создание новых стилей. Новые стили должны создаваться на основе фирменных стилей и сохранять фирменный подход к оформлению. 3.3. Параметры страницы В фирменном шаблоне назначены следующие параметры страницы: • размер листа; • ориентация листа; • переплет; • поля страницы. Изменение этих параметров запрещено. 3.4. Колонтитулы Каждая страница имеет верхний и нижний колонтитулы. Верхний колонтитул содержит: • наименование документа; • вид документа; • номер версии документа; • логотип компании. Нижний колонтитул содержит: • номер текущей страницы и общее количество страниц; • дату и время последней печати документа. Колонтитулы формируются автоматически на основе свойств документа. См. [1]. 3.5. Обязательные элементы документа 3.5.1. Титульный лист Титульный лист содержит: • наименование документа; • вид документа; • номер версии документа. Титульный лист формируется автоматически на основе свойств документа. См. [1]. 3.5.2. Содержание Содержание документа включает заголовки четырех уровней с наименованием разделов и указанием номеров страниц. Содержание формируется автоматически на основе заголовков документа. См. [1]. 3.5.3. Общие данные 3.5.3.1. Свойства Таблица 2. Свойства для документа Свойство Описание Название документа Определяет наименование документа (например, «Правила оформления документации»). Заполняется автоматически. См. [1]. Автор (Имя, должность, email) Определяет фамилию и имя автора документа, его должность и адрес электронной почты (например, «Гехт Софья. Технический писатель, sofya.gekht@gehtsoftusa.com»). Заполняется вручную. Статус документа Определяет статус документа (пример, «draft»). Заполняется вручную. Версия документа Определяет номер версии документа (пример, «1.0»). Заполняется автоматически. См. [1]. Вид документа Определяет вид документа (пример, «Стандарт»). Заполняется автоматически. См. [1]. Проект Определяет наименование проекта, к которому имеет отношение документ. Заполняется вручную. Свойство может быть исключено, если документ не относится к проектам (например, стандарт). Все перечисленные свойства обязательно должны быть заполнены. 3.5.3.2. Ссылки В этом разделе необходимо представить перечень источников. Источники оформляются в виде таблицы. В левой колонке указывается порядковый номер источника, в правой - информация о самом источнике. Информация об источнике должна быть достаточной для того, чтобы, в случае необходимости, его можно было легко найти. Например, если в документе есть ссылки на другой документ, книгу и Интернет ресурс, то: • для документа следует указать название, вид, номер версии и автора; • для книги - название, автора и год издания; • для Интернет ресурса - URL и краткое описание материала. Таблица 3. Пример оформления перечня источников Номер ссылки # Описание (Название, автор, дата, резюме) 1 Emailing Statements. Configuration Guide. Версия 2.0. Stanislav Bochkov. 2 Trading Systems and Methods. P. Kaufman. 1998 3 http://www.w3.org/Style/CSS/ - справочная информация о каскадных таблицах стилей. 3.5.3.3. История В этом разделе необходимо представить сведения об изменениях документа: когда, кем и какого рода изменения были внесены. Правила ведения "Истории" не регламентированы. При заполнении раздела рекомендуется соблюдать единообразие. 4. Требования к верстке документа 4.1. Заголовки Каждый раздел документа начинается с заголовка. Чтобы обеспечить вложенность разделов, в фирменном шаблоне определены стили для заголовков разных уровней. Таблица 4. Стили для заголовков Наименование Описание Стили для ненумерованных заголовков GSG Content Level 1 Ненумерованный заголовок первого уровня. GSG Content Level 2 Ненумерованный заголовок второго уровня. GSG Content Level 3 Ненумерованный заголовок третьего уровня. GSG Content Level 4 Ненумерованный заголовок четвертого уровня. GSG Content Level 5 Ненумерованный заголовок пятого уровня. Стили для нумерованных заголовков GSG Content Level 1 Numbered Нумерованный заголовок первого уровня. GSG Content Level 2 Numbered Нумерованный заголовок второго уровня. GSG Content Level 3 Numbered Нумерованный заголовок третьего уровня. GSG Content Level 4 Numbered Нумерованный заголовок четвертого уровня. Все заголовки разделов должны использовать один из стилей для нумерованных заголовков, за исключением заголовков следующих разделов: Раздел Стиль «Содержание» GSG Content Title «Общие данные» GSG Content Level 1 «Диаграммы» GSG Content Level 1 «Приложения» GSG Content Level 1 Диаграмма (вложен в раздел «Диаграммы») GSG Diagram Header Приложение (вложен в раздел «Приложения») GSG Appendix Текст заголовков следует начинать с заглавной буквы без заключительной точки. 4.2. Основной текст Для основного текста документа определен стиль GSG Normal. 4.3. Таблицы Таблица документа может иметь наименование. Для наименования таблицы необходимо использовать стиль GSG Table Num. Наименование должно состоять из номера и текста. Текст отделяется от номера точкой и должен начинаться с большой буквы. Точка в конце текста не ставится. Нумерация таблиц должна быть сквозной в пределах документа, включая приложения. Заголовок таблицы должен иметь серый фон и оформляться стилем GSG Header (Table). Тело таблицы оформляется стилем GSG Normal (Table). Допускается использовать таблицы, как с горизонтальным, так и с вертикальным заголовком. Таблица не должна выходить за границы текста. Рисунок 1 иллюстрирует примеры таблиц с горизонтальным и вертикальным заголовками.

Рисунок 1. Примеры оформления таблиц 4.4. Перечисления 4.4.1. Стили Для перечислений (списков) определен ряд стилей, которые позволяют строить многоуровневые (вложенные) перечисления. Таблица 5. Стили для перечислений, используемых в основном тексте: Наименование Описание Стили для маркированных перечислений GSG Enum 1 Маркированный элемент перечисления первого уровня. GSG Enum 2 Маркированный элемент перечисления второго уровня. GSG Enum 3 Маркированный элемент перечисления третьего уровня. GSG Enum 4 Маркированный элемент перечисления четвертого уровня. Стили для нумерованных перечислений GSG Enum Num 1 Нумерованный элемент перечисления первого уровня. GSG Enum Num 2 Нумерованный элемент перечисления второго уровня. Таблица 6. Стили для перечислений, используемых внутри таблицы Наименование Описание Стили для маркированных перечислений GSG Enum (Table) Маркированный элемент перечисления первого уровня. GSG Enum (Table) Маркированный элемент перечисления второго уровня. GSG Enum (Table) Маркированный элемент перечисления третьего уровня. GSG Enum (Table) Маркированный элемент перечисления четвертого уровня. Стили для нумерованных перечислений GSG Enum Num 1 (Table) Нумерованный элемент перечисления первого уровня. GSG Enum Num 2 (Table) Нумерованный элемент перечисления второго уровня. 4.4.2. Правила оформления Элементы перечисления следует писать с заглавной буквы, если предыдущее предложение завершено знаком конца предложения (точка, вопросительный знак и т.д.) Элементы такого перечисления также должны завершаться знаком конца предложения. Пример: Перечень требований, которые должны быть представлены в этом разделе, приведен ниже. • Требования к производительности. • Требования к конфиденциальности. • Информация и функции, которые должны быть защищены. • Категории пользователей и ограничения по доступу для каждой категории. • Требования к надежности. Элементы перечисления следует писать с маленькой буквы, если перечисление следует после двоеточия. Все элементы такого перечисления, исключая последний, должны завершаться точкой с запятой. Последний элемент перечисления должен завершаться точкой. Пример: В этом разделе должны быть представлены требования: • к производительности; • к конфиденциальности: • защита от несанкционированного доступа к продукту; • защита от несанкционированного доступа к платформе развертывания; • к надежности. 4.5. Формулы Для размещения формулы внутри документа необходимо использовать таблицу. Таблица должна состоять из одной строки и двух столбцов и иметь невидимые границы. В первую ячейку таблицы помещается объект формула «Microsoft Equation», во второй ячейке указывается порядковый номер формулы. Нумерация формул должна оформляться стилем GSG Formula и быть сквозной в пределах документа, включая приложения. Пример:

(1) 4.6. Графические объекты Рисунки и диаграммы должны иметь формат Windows Meta File, Enhanced Meta File или Computer Graphics Metafile (для векторных объектов) или GIF, JPG (для растровых объектов). Графический объект должен быть вставлен как символ (in-stream) (не фреймом), без возможности обтекания текстом. 4.6.1. Рисунки Рисунки могут быть расположены как по тексту документа, так и в разделе «Приложения». Каждый рисунок должен содержать номер и наименование. Для нумерации рисунков определен стиль GSG Picture Num. Например:

Рисунок 2. Логотип компании Gehtsoft 4.6.2. Диаграммы Диаграммы необходимо помещать в раздел документа «Диаграммы». Заголовок диаграммы оформляется стилем GSG Diagram Header, а диаграмма вставляется в абзац со стилем GSG Diagram. 4.7. Примеры кода Для примеров кода определен стиль GSG Source Code. Если спецификация метода дается на определенном языке программирования, то написание должно следовать соответствующему стандарту кодирования. 4.8. Ссылки 4.8.1. Перекрестные ссылки Ссылки на материал того же документа необходимо осуществлять только при помощи перекрестных ссылок. Перекрестные ссылки допускается использовать только при указании на: • заголовки разделов, в том числе приложения и диаграммы; • наименования таблиц; • наименования рисунков; • формулы. Перекрестная ссылка должна содержать номер или номер и название указываемого объекта. 4.8.2. Ссылки на источники информации Для того, чтобы сослаться на другой источник информации (документ, книгу, сайт), необходимо, в квадратных скобках указать порядковый номер источника из раздела «Ссылки». При ссылке на источник допускается указывать номер и/или заголовок раздела. Наименование заголовка следует за номером после разделительной запятой. Пример: Более подробную информацию о типах ордеров вы можете получить в [1], Ордера. 4.9. Термины и сокращения Термины и сокращения могут быть представлены как по ходу документа, так и в виде отдельных перечней. Термин, встречающийся в документе впервые, должен быть выделен курсивом. 4.10. Машинные строки (computer-related strings) Название классов, методы и свойства классов, переменные, значения переменных, теги, атрибуты и значения тегов, имена файлов следует помечать шрифтом Courier New, не изменяя другие атрибуты стиля. 4.11. Выравнивание текста по позициям При выравнивании текста по позициям следует использовать ручную настройку позиции табуляции, а не повторяющиеся пробелы или табуляции. 4.12. Не отрывать от следующего Заголовок раздела, наименование таблицы, абзац перед перечислением не должны отрываться от следующего абзаца. 4.13. Запрет висячих строк Последний элемент перечисления, заголовок таблицы или последняя строка таблицы не должны быть размещены на отдельной странице. 4.14. Пустые абзацы Запрещается присутствие в документе пустых абзацев. В случаях, когда требуется увеличить промежуток между абзацами, необходимо увеличить интервал «после» первого абзаца. 4.15. Переносы слов В документе запрещается использовать как автоматический, так и ручной перенос слов. 5. Инструменты для работы с документом 5.1. Горячие клавиши Для удобства работы со стилями большинству из них назначены горячие клавиши. Таблица 7. Фирменные стили, их описание и горячие клавиши Стиль Горячие клавиши Описание GSG Appendix Ctrl+Shift+A Заголовок подраздела «Приложение» (вложен в раздел «Приложения»). GSG Content Level 1 Ctrl+1 Ненумерованный заголовок первого уровня. GSG Content Level 1 Numbered Ctrl+Shift+1 Нумерованный заголовок первого уровня. GSG Content Level 2 Ctrl+2 Ненумерованный заголовок второго уровня. GSG Content Level 2 Numbered Ctrl+Shift+2 Нумерованный заголовок второго уровня. GSG Content Level 3 Ctrl+3 Ненумерованный заголовок третьего уровня. GSG Content Level 3 Numbered Ctrl+Shift+3 Нумерованный заголовок третьего уровня. GSG Content Level 4 Ctrl+4 Ненумерованный заголовок четвертого уровня. GSG Content Level 4 Numbered Ctrl+Shift+4 Нумерованный заголовок четвертого уровня. GSG Content Level 5 Ctrl+5 Ненумерованный заголовок пятого уровня. GSG Content Title - Заголовок раздела «Содержание». GSG Diagram - Стиль для диаграмм. GSG Diagram Header Ctrl+Shift+D Заголовок подраздела «Диаграмма» (вложен в раздел «Диаграммы»). GSG Enum 1 Alt+1 Маркированный элемент перечисления первого уровня. GSG Enum 1 (Table) Alt+Shift+1 Маркированный элемент перечисления первого уровня (для таблицы). GSG Enum 2 Alt+2 Маркированный элемент перечисления второго уровня. GSG Enum 2 (Table) Alt+Shift+2 Маркированный элемент перечисления второго уровня (для таблицы). GSG Enum 3 Alt+3 Маркированный элемент перечисления третьего уровня. GSG Enum 3 (Table) Alt+Shift+3 Маркированный элемент перечисления третьего уровня (для таблицы). GSG Enum 4 Alt+4 Маркированный элемент перечисления четвертого уровня. GSG Enum 4 (Table) Alt+Shift+4 Маркированный элемент перечисления четвертого уровня (для таблицы). GSG Enum Num 1 Alt+5 Нумерованный элемент перечисления первого уровня. GSG Enum Num 1 (Table) Alt+Shift+5 Нумерованный элемент перечисления первого уровня (для таблицы). GSG Enum Num 2 Alt+6 Нумерованный элемент перечисления второго уровня. GSG Enum Num 2 (Table) Alt+Shift+6 Нумерованный элемент перечисления второго уровня (для таблицы). GSG Normal Ctrl+~ Основной текст документа. GSG Normal (Table) Ctrl+Shift+~ Основной текст таблицы. GSG Picture Num Ctrl+0* Нумерация рисунков. GSG Table Num Ctrl+0 Нумерация таблиц. GSG SourceCode Ctrl+Shift+U Текст кода. GSG Title - Поля титульного листа. GSG Header (Table) - Заголовок таблицы. 5.2. Команды 5.2.1. Обновить все поля документа Обновляет титульный лист, колонтитулы, содержание, а также все перекрестные ссылки документа. Команда вызывается нажатием Alt+U. 5.2.2. Вставить формулу Вставляет формулу в соответствии с требованиями, регламентированными данным стандартом. Команда вызывается нажатием Alt+F. 5.2.3. Вставить таблицу Вставляет таблицу в соответствии с требованиями, регламентированными данным стандартом. Команда вызывается нажатием Alt+T. После нажатия Alt+T в документ будет вставлена таблица следующего вида:

Для команд, изменяющих таблицу, определены следующие горячие клавиши: Горячие клавиши Команда Alt+Shift+R Удалить текущую строку. Alt+Shift+C Удалить текущий столбец. Alt+C Добавить столбец слева от текущего столбца. Alt+R Добавить строку выше текущей строки. Alt+Shift+Стрелка вверх Переместить строку выше на одну позицию. Alt+Shift+Стрелка вниз Переместить строку ниже на одну позицию. 5.2.4. Вставить перекрестную ссылку Вызывает диалог для вставки перекрестных ссылок. Команда вызывается нажатием Ctrl+R. 5.2.5. Пометить выделенный текст как машинную строку Команда вызывается нажатием Ctrl+L. При повторном нажатии действие отменяется. 5.2.6. Изменить интервал "после" Стандарт запрещает присутствие в документе пустых абзацев. В случаях, когда требуется изменить промежуток между двумя абзацами, необходимо изменить интервал "после" первого абзаца. Для того, чтобы уменьшить интервал "после" для текущего абзаца, необходимо использовать сочетание клавиш Ctrl+<. Для того, чтобы увеличить интервал "после" для текущего абзаца необходимо использовать сочетание клавиш Ctrl+>. 5.2.7. Выбрать язык Вызывает диалог выбора языка и проверки правописания для выделенного фрагмента. Команда вызывается нажатием Alt+L. 5.2.8. Вставить неформатированный текст Вставляет неформатированный текст из буфера обмена. Команда вызывается нажатием Alt+Ctrl+V. Текст рекомендуется вставлять без форматирования при вставке из документа, созданного не на основе текущих фирменных ша