Правила хорошего тона при оформлении технической документации
Правила хорошего тона при оформлении технической документации
Введение
В ИТ-компаниях не сразу пришли к тому, что нужен технический писатель, а про нормоконтроль вообще не задумываются, пока не придет пачка замечаний от заказчика.
В компаниях пишется много документации, за которую отвечают не только технические писатели, но и аналитики, и руководители проектов, и технические специалисты. Важно понимать, что нельзя использовать технического писателя в качестве оформителя, это нецелесообразно по затратам компании. Можно по-разному преподносить информацию и качественное наполнение — это не всегда ключевой момент. «Комфортность» восприятия информации — это важно и может зависеть от способа изложения информации, визуализации данных на листе.
Нормоконтроль — на первый взгляд отголосок из Советского Союза или что-то связанное с Госзаказчиками. Но нормоконтроль (далее по тексту НК) — гигиена документа.
НК включает в себя не только правила русского языка (синтаксис/орфография), но и требования перекликающиеся с ГОСТ.
В этой статье я опишу примитивные требования к документации, с которыми столкнулась наша команда при взаимодействии с коммерческим заказчиком при сдаче текстовых документов в части оформления.
Требования к наименованию файла документа
Структура наименования файла документа выглядит следующим образом:
ХХХХ_YYYYY_V._._.ГГГГ.ММ.ДД, где:
ХХХХ — шифр согласно перечню документов;
YYYYY — наименование документа (например, Инструкция пользователей);
V._._. — версия документа;
ГГГГ.ММ.ДД — дата редактирования файла.
Шифр может содержать:
— Код Общероссийского классификатора предприятий и организаций;
— Код Классификатора ОКП 2;
— Код, принятый внутренней политикой компании.
Наименование документа может состоять из:
— Кода документа в соответствии с ГОСТ 34.201;
— Код документа или буквенное обозначение, принятый внутренней политикой компании.
Титульный лист
Титул — лицо документа, первое что видит пользователь, взяв документ в работу.
Для расположения блоков на титульном листе мне нравится использовать таблицу со скрытыми линиями. Расположение блоков для заполнения на титульном лист отображено на рисунке ниже.
Рисунок 1. Титульный лист
Нумерация страниц
Документ нумеруется со второго листа, на котором расположено чаще всего оглавление. Если после титульного листа вставляются листы согласования / подписания, то они не нумеруются, а нумерация листа оглавления также начинается со второго номера.
Колонтитулы в документе могут заполняться как сверху, так и снизу, если не используется рамка в документе (по ГОСТ 2–105). Целесообразно указывать наименование проекта / наименование документа / шифр документа.
Если для оформления документа используются определенные размеры полей, то стоит учесть, что колонтитул не должен выходить за рамки этих полей. Для определения данного условия в MS Word используется режим «Сетка».
Оглавление
Для удобочитаемости и восприятия информации отступами выделяю первый, второй и третий уровни оглавления. Если мы будем выделять и последующие уровни, то мы получим бесконечную лестницу, а на листе в конце концов не останется места.
Рисунок 2. Оглавление
Оформление заголовков
Заголовки разделов, подразделов и приложений печатают с прописной буквы без точки в конце, полужирным шрифтом.
Переносы слов в заголовках не допускаются.
Заголовки разделов (первого уровня) нумеруют арабскими цифрами с точкой, например:
Пример 1
Заголовки подразделов (второго и последующих уровней) нумеруют арабскими цифрами, разделенными точкой, и без точки после номера, например:
Пример 2
Пример 3
Заголовок раздела/подраздела и текст изложения должны располагаться на одной странице. Для соблюдения этого необходимо в меню «Абзац» стиля заголовка во вкладке «Положение на странице» отметить поле «не отрывать от следующего».
Рисунок 3. Положение на странице для абзаца стиля
Основной текст
По использованию стиля для основного текста в интернете существует масса информации, я подробно останавливаться не буду.
Основные требования к написанию текста опишу ниже.
В тексте документа не допускается применять:
− обороты разговорной речи, техницизмы, профессионализмы;
− для одного и того же понятия различные научно-технические термины, близкие по смыслу, а также иностранные слова и термины при наличии равнозначных слов и терминов в русском языке;
− произвольные словообразования;
− сокращения слов, кроме установленных правилами русского языка и соответствующим разделом документа.
В документе не используют перенос слов.
В тексте документа используют:
− буквы «Ё», «ё» без точек, в том числе в именах собственных;
− кавычки с русской раскладки клавиатуры.
Не допускается:
− переносить на следующую строку (страницу) только номер структурного элемента (рисунка, таблицы, раздела, приложения и т.д.);
− разносить на разные строки или в разные стороны графы таблицы форму собственности (АО, ООО и пр.) и наименование организации, а также инициалы и фамилию;
− отделять на разные строки единицу величины от числового значения;
− отделять на разные строки знак номера от числа.
Рекомендуется в таком случае использовать неразрывный пробел (сочетание клавиш Shift+Ctrl+Пробел).
В тексте документа следует избегать:
− двойных пробелов;
− пустых абзацев;
− разнесения на разные строки частей сложносоставных слов, написанных через дефис.
Не допускается использование лишних абзацев для отступа текста, двойных и более пробелов.
В тексте документа должны быть ссылки на все имеющиеся в нем таблицы, рисунки, приложения.
При указании ссылок на несколько элементов используют следующие формулировки:
»…приведено в таблицах 1–4»,»…в приложениях 1–3»,»…как показано на рисунках 1 и 2»,»… на рисунках 1–4», а также как показано на рисунке ниже.
Рисунок 4. Ссылка на несколько рисунков в тексте
Оформление рисунков
Любой графический материал (чертеж, схема, диаграмма, рисунок и т.п.) обозначают в документе словом «рисунок». Рисунки нумеруют сквозной нумерацией по тексту документа, включая приложения.
Рисунки располагают непосредственно после текста, в котором о нем упоминается впервые, или на следующей странице, а при необходимости в отдельном приложении. Переносить на следующую строку (страницу) только номер рисунка не допускается. Ссылка на рисунок должна располагаться в конце предложения.
Для указания последовательности выполнения описанных в тексте шагов к ссылке на рисунок добавляют арабские цифры, заключенные в квадратные скобки. На рисунке эти же шаги обозначают цифрами, при необходимости нужную область выделяют цветной рамкой. Пример оформления ссылок на описанные в тексте шаги приведен на рисунке ниже.
Рисунок 5. Пример отображения ссылок на последовательность действий
Рисунки в тексте должны иметь рамку в виде сплошной линии черного цвета.
При использовании в рисунках блок-схем необходимо приводить поясняющие данные к элементам блок-схемы (легенда).
Наименование рисунка включает слово «Рисунок», порядковый номер, после которого проставляют точку. Далее, через пробел, с прописной буквы указывают тематическое наименование. Для наименования рисунка используют высоту шрифта основного текста.
Оформление таблиц
Таблицы нумеруют арабскими цифрами сквозной нумерацией в пределах всего документа, включая приложения. На все таблицы документа должны быть приведены ссылки в тексте документа, при ссылке следует писать слово «таблица» с указанием ее номера.
Таблицы располагают непосредственно после текста, в котором о нем упоминается впервые, или на следующей странице, а при необходимости в отдельном приложении.
Для абзаца текста после таблицы следует добавить интервал «Перед».
Для строки с заголовками следует включить «повторять как заголовок на каждой странице», если таблица располагается на нескольких листах.
Оформление приложений
Приложения располагают после основного текста документа. Каждое приложение начинают с новой страницы. Приложения нумеруют арабскими цифрами в порядке их упоминания в тексте и располагают в порядке возрастания номеров.
Приложения имеют общую с основным текстом документа сквозную нумерацию страниц.
