Техническое письмо — итоги
ERD и словарь сущностей — Entity Relationship, нормализация, SQL. Карта — о разделе.
Кратко — что стоит унести из раздела "Техническое письмо". Если пункт кажется туманным — откройте указанную главу или оглавление.
FAQ — Часто задаваемые вопросы
Типичные затыки при написании и сдаче документации — ГОСТ vs wiki, OpenAPI, устаревшие инструкции и разные аудитории. Термины для самопроверки — в чек-листе.
Вопрос. "Документация потом" — релиз через неделю, README пустой. С чего начать?
Ответ. Минимум для эксплуатации: как установить, как откатить, куда смотреть логи, кому звонить. Один runbook лучше нуля страниц ГОСТ. Подробнее здесь — Техническое письмо, Качество документации.
Вопрос. Разработчик говорит "код и есть документация" — заказчик требует ТЗ.
Ответ. Код описывает реализацию, а не обязательства, сценарии пользователя и приёмку. Для контракта нужны согласованные артефакты; для команды — wiki и OpenAPI параллельно. Подробнее здесь — Документация, ТЗ по ГОСТ.
Вопрос. Один модуль — кому писать: пользователю, оператору или программисту?
Ответ. Разным ролям — разные руководства: пользователь — сценарий "сделать отчёт", оператор — кнопки и аварии, программист — API и структуры. Смешение в одном PDF путает всех. Подробнее здесь — Виды документации, Руководство пользователя.
Вопрос. OpenAPI сгенерировали из кода — интегратор жалуется на расхождения с prod.
Ответ. Code-first без CI-проверки устаревает молча. Нужны contract tests, ревью breaking changes и версионирование API. Подробнее здесь — Документирование API.
Вопрос. Design-first: написали spec, разработка ушла в другую сторону — кто прав?
Ответ. Spec — контракт, пока не согласован change. Если меняется реализация — обновляют spec и версию API, иначе интеграторы ломаются. Подробнее здесь — Документирование API.
Вопрос. Swagger UI красивый, но примеры запросов не работают — зачем он?
Ответ. Живые примеры требуют актуальных auth, env и seed-данных. Без этого UI — витрина; добавьте mock-сервер или sandbox. Подробнее здесь — Документирование API.
Вопрос. ГОСТ требует 19 документов — Agile-команда в панике.
Ответ. Используйте навигатор: что обязательно по контракту, что можно вести как wiki с экспортом, что генерируется из репозитория. Подробнее здесь — Навигатор по нормативке, Архитектура документации.
Вопрос. ТЗ на 200 страниц никто не читает — как не превратить в мусор?
Ответ. Структура по ГОСТ + живой traceability к задачам и тестам. Крупные таблицы — в приложения; в теле — решения и критерии. Подробнее здесь — ТЗ по ГОСТ, Качество документации.
Вопрос. ПМИ написали после релиза — приёмка срывается.
Ответ. ПМИ связывают требования и проверки; их пишут параллельно ТЗ, а не "для галочки". Иначе непонятно, что именно принимают. Подробнее здесь — ПМИ по ГОСТ.
Вопрос. Пояснительная записка дублирует презентацию для заказчика — можно сократить?
Ответ. ПЗ фиксирует обоснование решений и состав для экспертизы, а не презентацию для заказчика. Подробнее здесь — ПЗ по ГОСТ.
Вопрос. Руководство оператора vs администратора — заказчик требует "одно на всех".
Ответ. Оператор работает с прикладным UI, администратор — с пользователями, правами, бэкапами. Смешение повышает риск ошибок на prod. Подробнее здесь — Руководство оператора, Руководство администратора.
Вопрос. Стиль "как в PDF гайде" мешает точности — можно отступить?
Ответ. Да, если обосновать локально (безопасность, однозначность API) и согласовать с владельцем документации. Глобальный хаос стилей хуже одного исключения. Подробнее здесь — Стилевые паттерны.
Вопрос. Комментарии в коде на русском, doc на английском — норма?
Ответ. Зависит от политики команды и аудитории. Главное — единообразие в одном модуле и актуальность; смешение языков в одном файле мешает онбордингу. Подробнее здесь — Стилевые паттерны.
Вопрос. Confluence устарел, но "официальный" — разработчики читают README в Git.
Ответ. Нужен единый source of truth: либо docs-as-code в репо с sync, либо владелец wiki с регламентом обновления после merge. Два противоречащих источника хуже одного. Подробнее здесь — Экосистема технического письма, Архитектура документации.
Вопрос. Docs-as-code — кто должен обновлять markdown при каждом PR?
Ответ. Автор изменения + ревьюер проверяет, затронута ли doc. CI может падать, если нет записи в changelog или OpenAPI. Подробнее здесь — Экосистема технического письма.
Вопрос. Скриншоты UI в доке устарели после редизайна — как поддерживать?
Ответ. Меньше pixel-perfect скринов, больше номеров элементов и имён полей; автогенерация где возможно; checklist перед релизом на doc-ревью. Подробнее здесь — Качество документации.
Вопрос. Техписа нет в штате — кто пишет руководства?
Ответ. Черновики — аналитик и разработчик, редактура и структура — техпис или тимлид; шаблоны и глоссарий снижают барьер. Подробнее здесь — Технический писатель.
Вопрос. Ошибки API описаны как "что-то пошло не так" — интеграторы бесятся.
Ответ. Для каждого кода — причина, действие, retry/idempotency. Таблица ошибок в spec обязательна для B2B API. Подробнее здесь — Документирование API, Качество документации.
Вопрос. Глоссарий есть, но все пишут "лid", "заказ", "order" по-разному.
Ответ. Глоссарий работает, когда линтер в PR и владелец терминов его обновляют. Мёртвая таблица в Confluence не меняет язык команды. Подробнее здесь — Качество документации.
Вопрос. Word/Excel от заказчика — единственный "источник правды" для требований.
Ответ. Зафиксируйте версию файла и процесс изменений; лучше импорт в трекер или docs с diff. Правки в почте без номера версии — классический источник багов. Подробнее здесь — Word и Excel в документации.
Вопрос. Микросервисы — одна "книга" или doc на сервис?
Ответ. Каталог сервисов + контракт каждого API и сквозные сценарии (sequence) для сквозных потоков. Монолитный PDF быстро устаревает. Подробнее здесь — Архитектура документации.
Вопрос. Релиз каждую неделю — как не захламить версиями PDF для госзаказчика?
Ответ. Договоритесь о реестре версий, приложениях к акту и электронном комплекте; не каждый patch требует новой печати, если регламент позволяет. Подробнее здесь — Навигатор по нормативке.
Вопрос. Ревью документации никто не делает — все подписывают.
Ответ. Включите doc в Definition of Done и назначьте ревьюера не-автора (QA, второй dev). Подпись без чтения — формальность с риском на приёмке. Подробнее здесь — Качество документации.
Вопрос. Новичок не понимает doc — это проблема новичка или текста?
Ответ. Проверка тестом "15 минут без наставника". Если не проходит — упрощают структуру, добавляют quick start, не добавляют жаргон. Подробнее здесь — Техническое письмо, Качество документации.
Вопрос. Диаграммы в doc не совпадают с prod-архитектурой — кому верить?
Ответ. Prod + IaC — источник для инженеров; схемы обновляют при архитектурных ADR или автогенерации из мониторинга. Подробнее здесь — Архитектура документации.
Вопрос. Локализация doc — перевели UI, но инструкция на русском для EN-рынка.
Ответ. Строки UI и doc должны идти одним пайплайном локализации; иначе support получает двойную работу. Подробнее здесь — Качество документации.
Вопрос. Решение из чата не попало в wiki — через месяц все спорят заново.
Ответ. Правило: важное решение → ADR или страница wiki в 24 часа. Аналитик или тимлид — владелец фиксации. Подробнее здесь — Экосистема технического письма, Базы знаний.
Ниже — формулировки, которые часто вводят в Google и Яндексе; короткий ответ и ссылка на материал раздела.
Вопрос. Техническое письмо в IT — что это?
Ответ. Дисциплина передачи знаний так, чтобы повторить, проверить и принять систему: ТЗ, API, runbook, руководства. Подробнее здесь — Техническое письмо.
Вопрос. Техническое задание на разработку ПО — что должно быть внутри?
Ответ. Цели, функции, требования, ограничения, приёмка — по ГОСТ 34 или согласованному шаблону заказчика. Подробнее здесь — ТЗ по ГОСТ.
Вопрос. ГОСТ 34 документация на программу — какие документы?
Ответ. ТЗ, спецификация, ПМИ, пояснительная записка, руководства по ролям — комплект ЕСПД для контракта. Подробнее здесь — Навигатор по нормативке.
Вопрос. Спецификация на программное обеспечение — зачем нужна?
Ответ. Фиксирует состав ПО, модули и связи — основа для разработки и приёмки. Подробнее здесь — Спецификация по ГОСТ.
Вопрос. ПМИ (программа и методика испытаний) — что это?
Ответ. Документ с сценариями и критериями тестов для формальной приёмки системы. Подробнее здесь — ПМИ по ГОСТ.
Вопрос. Swagger OpenAPI — как документировать REST API?
Ответ. Описывают контракт (paths, schemas, errors) в YAML/JSON; UI и codegen — производные. Подробнее здесь — Документирование API.
Вопрос. Руководство пользователя — как написать понятное?
Ответ. Сценарии "сделать X", скриншоты/номера элементов, без внутренней архитектуры. Подробнее здесь — Руководство пользователя.
Вопрос. Чем ТЗ отличается от спецификации?
Ответ. ТЗ — требования и контекст; спецификация — состав и структура программы как изделия. Подробнее здесь — ТЗ по ГОСТ, Спецификация.
Вопрос. Docs as code — что это?
Ответ. Документация в Git рядом с кодом, ревью в PR, сборка сайта в CI — как исходники. Подробнее здесь — Экосистема технического письма.
Вопрос. Технический писатель (technical writer) — чем занимается?
Ответ. Структурирует знания, пишет и редактирует doc для разных аудиторий, держит стиль и актуальность. Подробнее здесь — Технический писатель.
Вопрос. Пояснительная записка к программе — что в ней пишут?
Ответ. Обоснование решений, архитектура, состав, ожидаемые характеристики для экспертизы. Подробнее здесь — ПЗ по ГОСТ.
Вопрос. Руководство программиста по ГОСТ — для кого?
Ответ. Для разработчика/интегратора: API, структуры, конфиги, сборка модуля. Подробнее здесь — Руководство программиста.
Вопрос. Руководство администратора и оператора — в чём разница?
Ответ. Оператор — прикладные операции; администратор — пользователи, права, бэкапы, инфраструктура приложения. Подробнее здесь — Руководство оператора, Руководство администратора.
Вопрос. Design-first и code-first API — что выбрать?
Ответ. Design-first — контракт до кода; code-first — spec из реализации. Оба работают при синхронизации в CI. Подробнее здесь — Документирование API.
Вопрос. ГОСТ 19 и ГОСТ 34 — в чём разница для документации?
Ответ. 19 — документы на программу как изделие; 34 — на автоматизированные системы. Навигатор подскажет нужный комплект. Подробнее здесь — Навигатор по нормативке.
Вопрос. Confluence или README в Git — где хранить документацию?
Ответ. Git — для технической doc рядом с кодом; Confluence — для живых регламентов и бизнес-контекста. Подробнее здесь — Архитектура документации.
Вопрос. Runbook — что писать в operational документации?
Ответ. Шаги при инциденте, деплое, откате, контакты, метрики — проверяемые команды, не prose. Подробнее здесь — Качество документации.
Вопрос. ADR (Architecture Decision Record) — зачем?
Ответ. Краткая фиксация решения, контекста и последствий, чтобы через год не спорить "почему так". Подробнее здесь — Архитектура документации.
Вопрос. Глоссарий проекта — зачем нужен?
Ответ. Единые термины для команды, заказчика и doc — меньше багов из-за разных "заказов". Подробнее здесь — Качество документации.
Вопрос. Нужна ли документация в Agile?
Ответ. Да, но достаточная: wiki, OpenAPI, DoD; формальный ГОСТ — если требует контракт. Подробнее здесь — Виды документации.
Вопрос. Ревью технической документации — кого привлекать?
Ответ. Второй инженер, QA, представитель аудитории; не только автор. Подробнее здесь — Качество документации.
Вопрос. Руководство системного программиста — что описывает?
Ответ. Установка на ОС и железо, конфиги, порты, интеграция с инфраструктурой. Подробнее здесь — Руководство системного программиста.
Что запомнить
Раздел собрал три линии — зачем и как писать (теория и стиль), живые форматы (API, wiki, комментарии в коде) и формальные комплекты (ЕСПД, руководства по ролям, навигатор 19 vs 34).
Главное, что стоит унести с собой
Техническое письмо — способ передать знание так, чтобы его можно было проверить — повторить шаг, прогнать тест, сдать приёмку.
Аудитория определяет форму. Один и тот же модуль описывают по-разному для оператора (кнопки), системного программиста (конфиги и порты), программиста (контракты и структуры) и пользователя (сценарий "сделать отчёт").
Стиль — компромисс, не закон. Гайдлайны экономят время команды, но задача важнее шаблона: если правило мешает точности — его нужно обоснованно нарушить в ограниченной зоне, а не "потому что так в PDF".
OpenAPI и аналоги отделяют контракт от реализации: спецификация может жить раньше кода (design-first) или генерироваться из него (code-first) — оба пути рабочие, если документ остаётся источником истины для интеграторов.
ГОСТ и Agile не враги. Wiki и user stories ускоряют работу; утверждённый ТЗ, спецификация и ПМИ фиксируют обязательства. Аналитик следит, чтобы решения из чата не остались только в чате.
Карта раздела
| Блок | Ключевые главы |
|---|---|
| Введение | Техническое письмо, Документация, Виды документации, Технический писатель |
| Качество и стиль | Качество документации, Стилевые паттерны технической документации |
| API | Документирование API с использованием Swagger/OpenAPI |
| Нормативка программы | Навигатор по нормативной документации, Техническое задание по ГОСТ–ПЗ по ГОСТ |
| Руководства | Руководство системного программиста по ГОСТ–Руководство администратора по ГОСТ, Руководство пользователя по ГОСТ |
| Самопроверка | Техническое письмо — чек-лист |
Перед экзаменом, собеседованием или сдачей комплекта пройдите чек-лист самопроверки — там 50 вопросов по всему разделу.
Куда идти дальше
| Тема | Раздел |
|---|---|
| "Основы интеграционного взаимодействия — о разделе" | "Основы интеграционного взаимодействия — о разделе" |
| "Low-code и No-code платформы" | "Low-code и No-code платформы" |
| "Аутентификация и авторизация" | "Аутентификация и авторизация" |
| "SQL — о разделе" | "SQL — о разделе" |
Проверьте себя: Чек-лист самопроверки.