Требования к оформлению технической документации.

Требования к оформлению технической документации

ГОСТ Р 2.105‑2019 — общие требования к текстовым документам: структура, шрифты, интервалы, оформление таблиц и иллюстраций. Обязателен для госзаказов и ряда корпоративных проектов.
ГОСТ 19 (ЕСПД) и ГОСТ 34 — регламентируют состав и оформление документации на ПО и автоматизированные системы (перечни документов, правила заполнения реквизитов, обозначения).
IEEE и ISO (например, ISO/IEC/IEEE 29148) — международные стандарты для спецификаций требований и проектных описаний; применяют в кросс‑бордерных и аутсорс‑проектах.

Шрифты и размер: основной текст — 11–14 пт, для таблиц, примечаний и примеров — на 1–2 пт меньше. В стандартизированных документах избегают проприетарных шрифтов (Arial, Times New Roman) в пользу открытых или гарантированно доступных в целевой среде.
Интервалы и отступы: полуторный межстрочный интервал, абзацный отступ — 5 знаков (≈1,25 см), поля — не менее 20 мм (левое — 30 мм для подшивки).
Терминология: используют стандартизированные термины и определения; синонимы и разговорные обороты исключают. Для неоднозначно трактуемых понятий вводят раздел «Термины и определения» или глоссарий.
Формулировки: для обязательных требований применяют слова «должен», «следует», «необходимо»; для допустимых вариантов — «допускается», «может быть».

Обязательные: титульный лист, содержание (для документов >10 страниц), основное тематическое содержание, лист регистрации изменений (в регламентированных проектах).
Дополнительные (по необходимости): предисловие, обозначения и сокращения, термины и определения, приложения, библиография, ссылочные документы.
Нумерация: сквозная нумерация разделов, подразделов и пунктов (например, 3.2.1); рисунки и таблицы — отдельная нумерация либо по разделам (Рис. 2.3, Табл. 1.1).

Таблицы: заголовки граф — полужирный шрифт, выравнивание по центру; строки — без лишних горизонтальных линий, если это не ухудшает читаемость. Повторяющийся текст в ячейках заменяют кавычками или фразой «То же», кроме цифр.
Иллюстрации: размещают после первого упоминания в тексте либо на следующей странице. Подпись — «Рис. X.Y. Наименование», центрированная, без точки в конце. Диаграммы (UML, C4, Mermaid) включают как изображения или генерируемые блоки с версией на момент фиксации документа.

Форматы: PDF/A для долговременного хранения и передачи, Markdown/AsciiDoc — для совместной работы и версионирования в Git, HTML/Confluence — для внутренней базы знаний.
Версионирование: указывают номер версии, дату выпуска, автора и статус (черновик/на согласовании/утверждён). В Git‑документации используют changelog и семантическое версионирование.
Автогенерация: API‑документацию формируют из OpenAPI/Swagger, комментарии в коде — через Doxygen/Sphinx/Javadoc. Это снижает расхождение между кодом и описанием.

Единообразие: один стиль оформления для всех документов проекта (шаблоны Confluence, Word, LaTeX).
Актуальность: фиксируют дату последнего обновления на титульном листе и в метаданных; при изменениях ведут лист регистрации или changelog.
Доступность: избегают сложных оборотов и аббревиатур без расшифровки; для внешних интеграторов добавляют раздел «Глоссарий» и «Быстрый старт».
Контроль качества: чек‑лист проверки перед публикацией (наличие титульного листа, нумерации, ссылок на приложения, корректность терминов, отсутствие «висячих» строк и разрывов таблиц).