О разделе
Раздел про техническое письмо — как переводить сложные системы (код, API, процессы, ГОСТ-документы) в текст, который другой человек поймёт с первого раза и сможет применить без "оракула в соседнем кабинете".
Здесь три слоя:
- База — что такое документация, роль техписателя, виды артефактов, качество текста.
- Практика — API (OpenAPI), стиль, комментарии в коде, docs-as-code.
- Нормативка — ТЗ, спецификация, ПМИ, руководства по ролям (ЕСПД и современные аналоги).
Если вы впервые в теме — начните с Техническое письмо, затем Виды документации. Для госпроекта или диплома сразу откройте Навигатор по нормативной документации.
Как читать
| Глава | Тема | Кому в первую очередь |
|---|---|---|
| Техническое письмо | Зачем, история, комментарии, API, wiki | Всем |
| Документация | Документ vs документация, внутренняя/внешняя | Новичкам |
| Виды документации | API, ADR, runbook, эксплуатационные виды | Разработчикам, аналитикам |
| Технический писатель | Роль, цикл работы, среды | Тем, кто пишет профессионально |
| Качество документации | Метрики понятности, типичные провалы | Руководителям, ревьюерам |
| Архитектура документации | Элементы, стили, шаблоны | Руководителям, техписам |
| Word и Excel в проектной документации | Оглавление, реестр требований, рецензирование | Аналитикам, перед сдачей DOCX |
| LaTeX — формулы для отчётов | Дроби, интегралы, шаблон лабораторной | Студентам STEM, школьным олимпиадникам |
| SymPy — уравнения и производные | Корни, производные, LaTeX из Python | Школа, матан, проверка ДЗ |
| Swagger / OpenAPI | Спецификация REST API | Backend, интеграторы |
| Стилевые паттерны | Гайдлайны без догмы | Редакторам, авторам |
| Навигатор по ГОСТ | Серия 19 vs 34, стадии, мост к Agile | Аналитикам, архитекторам |
| ТЗ · Спецификация · ПМИ · ПЗ | Комплект на программу | Госсектор, учёба |
| Руководства по ролям | Системный программист, программист, оператор, ТО, пользователь, админ | По вашей роли — см. таблицу ниже |
Какой документ читать по роли
| Вопрос читателя | Документ в ЕСПД | Глава энциклопедии |
|---|---|---|
| Как нажимать кнопки в смену? | Руководство оператора (19.505) | Руководство оператора по ГОСТ |
| Как установить на сервер и настроить ОС? | Руководство системного программиста (19.503) | Руководство системного программиста по ГОСТ |
| Как устроен код и куда стыковаться? | Руководство программиста (19.504) | Руководство программиста по ГОСТ |
| Как завести пользователей и роли в приложении? | По аналогии с 19.505 (отдельного ГОСТ нет) | Руководство администратора по ГОСТ |
| Как решить свою задачу без терминала? | Руководство пользователя (ГОСТ Р 59795) | Руководство пользователя по ГОСТ |
| Как проверить, что всё работает перед сдачей? | ПМИ (19.301) | ПМИ по ГОСТ |
Рекомендуемый маршрут новичка: 1 → 1001 → 1002 → 3 → 11.
Маршрут перед сдачей госпроекта: 22 → 12 → 13 → 14 → нужное руководство по роли.
Теория, которую стоит держать в голове
Diátaxis — четыре типа страниц — tutorial (учимся), how-to (решаем задачу), reference (справочник), explanation (почему так). Одна и та же система описывается по-разному; смешивать типы в одной статье — частая причина "простыни, которую никто не дочитал".
Трассируемость — каждое требование в ТЗ должно где-то проверяться (ПМИ, тест, пункт руководства). Без связи "требование → проверка" приёмка превращается в спор о формулировках.
Docs-as-code — Markdown в Git, ревью как у кода, версия документа рядом с версией продукта. Автоматизация сборки сайта — опциональна; ядро — хранение и ревью.
Сеть и API в документации — OpenAPI и руководства программиста описывают то, что уже должно быть понятно из теории: 2.09 Интеграция, HTTP, аутентификация. Практика контракта — Swagger/OpenAPI и API в 7.06.
Модели данных в документации — ERD, словарь сущностей и описание миграций опираются на Entity Relationship, нормализацию и проектирование БД; регламентные обмены — пакетная работа с данными.
Оформление документов (практика)
Ниже — тренажёры по базовому оформлению в Word и Excel. Они не заменяют раздел про техпис, но помогают, если вам нужно сверстать формальный комплект или таблицу требований. Пошаговые рецепты — в Word и Excel в проектной документации; базовый курс — Word и Excel. Отчёт с формулами и PDF для вуза — LaTeX — формулы для отчётов; расчёт корней и производных в Python — SymPy — уравнения и производные.
Play ITЗагрузка интерактивного демо…
Play ITЗагрузка интерактивного демо…
Техническое письмо
Техническое письмо - это когда мы объясняем сложную штуку (кнопки, код, болты, законы) так, чтобы другой человек понял её с первого раза и не накосячил.
Документация
Документация — это совокупность документов, созданных для описания, объяснения, сопровождения или управления продуктом, системой, процессом или проектом.
Виды документации
В мире существует очень, ОЧЕНЬ много видов документов. Вы даже себе не представляете, насколько.
Технический писатель
Технический писатель - специалист, занимающийся написанием технической документации.
Качество документации
Хорошая документация — это та, которую не нужно объяснять устно. Если команда постоянно уточняет — А в документе это имеется в виду так-то? — значит, документация недостаточно ясна.
Архитектура документации
Архитектура документации — это целенаправленное проектирование структуры, содержания, форматов, потоков и взаимосвязей всех документов, сопровождающих продукт или систему на всех этапах её жизненного.
Экосистема технического письма
Markdown Extra — используется в некоторых генераторах (например, в MkDocs) для расширенных возможностей.
Word и Excel в проектной документации
Практические рецепты Word и Excel для ТЗ, реестров требований, оглавлений и рецензирования — мост между офисной грамотностью и техническим письмом.
Стилевые паттерны технической документации
Стилевой паттерн - это готовый шаблон того, как писать и оформлять код или текст.
Техническое задание по ГОСТ
Техническое задание (ТЗ) — это документ, в котором заказчик и исполнитель договорились о правилах игры до того, как кто-то начал что-то делать.
Спецификация по ГОСТ
Спецификация - это список всех деталей и инструкций к ним, которые входят в поставку программы. Опись того, за что платят и что получают.
ПМИ по ГОСТ
ПМИ - это документ, в котором написано, как будут проверять, работает ли программа так, как надо.
ПЗ по ГОСТ
Если используется open-source компонент, указывайте название, версию, лицензию и источник.
Руководство системного программиста по ГОСТ
Руководство системного программиста — это инструкция для того, кто ставит и настраивает программу на сервере.
Руководство программиста по ГОСТ
Рекомендация — оформлять в виде таблиц. Ошибка — смешивать требования к системе и требования к разработке.
Руководство оператора по ГОСТ
Руководство оператора - это документ о том, как выполнять конкретные операции — пошагово, с картинками интерфейса.
Руководство по техническому обслуживанию по ГОСТ
Основано на ГОСТ 19.508-79.
Руководство пользователя по ГОСТ
Основано на ГОСТ Р 59795 – 2021. Руководство пользователя о том, как выполнить сценарии, нужные пользователю: зарегистрироваться, заказать товар, посмотреть баланс, выгрузить отчёт.
Руководство администратора по ГОСТ
Не указывайте любой современный браузер. Указывайте конкретные версии и режимы, например Chrome >=115.
Навигатор по нормативной документации
Когда применять комплект документов на программное изделие, когда — на автоматизированную систему, какие артефакты нужны на каждой стадии и как связать их с современной практикой аналитики.
Документирование API с использованием Swagger/OpenAPI
API — прикладные программные интерфейсы — служат основным каналом взаимодействия между компонентами систем, между внутренними сервисами и внешними клиентами, между разработчиками и пользователями.
Техническое письмо — итоги
Итоги раздела «Техническое письмо» — FAQ и краткие ответы по теме.
Техническое письмо — чек-лист
Чек-лист раздела «Техническое письмо» — вопросы для самопроверки.
Техническое письмо — о разделе
Подборка материалов раздела Техническое письмо в энциклопедии Вселенная IT.
В подборках
Статья входит в тематические подборки и блок "С чего начать?" на главной. Соседние шаги того же маршрута:
Системная аналитика — Основы интеграционного взаимодействия — о разделе, Low-code и No-code платформы, Аутентификация и авторизация, SQL — о разделе, Основы архитектуры, Платформенные решения в бизнесе.