Как документировать самописные модули и интеграции
Содержание 13 разделов
Чтобы знания о системе не уходили вместе с разработчиком
Почему об этом вообще приходится говорить
Самописный модуль или интеграция обычно появляются под конкретную задачу: обменять заказы между сайтом и 1С, подключить банк по API, передать документы в государственную систему. Пока модуль пишет один и тот же человек, документация кажется необязательной — контекст у него в голове. Проблема появляется позже: при смене разработчика, при обновлении внешней системы, при инциденте ночью, когда разбираться нужно не автору кода, а дежурному администратору.
Эта статья — не про то, как красиво оформить README. Она про то, какой минимальный состав документации закрывает реальные риски: потерю знаний при уходе специалиста, поломку интеграции при обновлении API партнёра, невозможность объяснить регулятору, что делает система.
Что считать документацией модуля и интеграции
Полезно сразу разделить два разных объекта документирования, потому что для них нужны разные документы:
- Модуль — это код, который выполняет функцию внутри системы (доработка 1С, внутренний сервис, библиотека). Для него важны: назначение, входные и выходные данные, зависимости, правила изменения, история доработок.
- Интеграция — это обмен данными между двумя и более системами. Для неё важны: контракт обмена, направление и формат данных, правила ошибок и повторов, безопасность канала, эксплуатационные действия при сбое.
Для простого внутреннего обмена иногда достаточно короткого контракта и README рядом с кодом. Для интеграции, от которой зависят деньги, статусы заказов, персональные данные или отчётность перед государством, нужен полный комплект — карта, контракт, данные, ошибки, безопасность, тесты и порядок действий при сбое. Это не просто техническое приложение к ТЗ: по нему аналитик согласует смысл данных, разработчик пишет обмен, тестировщик проверяет сценарии, администратор видит настройки, а поддержка действует при сбое [1].
Из чего состоит документация интеграции
Карта обменов и контракт
Прежде всего документация должна отвечать на три простых вопроса: какие системы обмениваются данными, какой контракт они обязуются соблюдать и что делать при ошибке. Документировать интеграции и API нужно до разработки, а не после первого сбоя обмена [1].
Контракт должен быть достаточным, чтобы обе стороны разрабатывали обмен без устных уточнений: какие методы или события существуют, какие поля обязательны, какие форматы дат и сумм используются, что происходит при частичном или пустом ответе. Отдельно фиксируют, что считается «breaking change» и какой период поддерживается старая версия контракта.
Данные, ошибки и идемпотентность
Самая частая причина проблем в интеграциях — не отсутствие метода API, а разное понимание данных сторонами обмена [1]. Поэтому рядом с контрактом нужен словарь данных: что означает каждое поле, кто владелец справочника, какие значения допустимы и что делать при расхождении источников.
Отдельно стоит описать поведение при повторной отправке одного и того же события (идемпотентность) и правила ретраев — какие ошибки можно повторять автоматически, а какие требуют ручного разбора. Для тестирования полезно иметь не только успешный сценарий, но и минимум один пример бизнес-отказа и один пример технической ошибки на каждый ключевой метод.
Безопасность и доступы
Даже внутренний обмен между своими системами требует правил доступа: кто может вызвать метод, какие ключи или сервисные учётные записи используются, как они ротируются и что делать при компрометации секрета. Отдельно фиксируют, какие данные нельзя писать в логи — это особенно важно, если через интеграцию проходят персональные данные.
Runbook и наблюдаемость
Runbook — это документ на случай, когда обмен уже сломался. В него включают: признаки сбоя (рост очереди, таймауты, ошибки авторизации), порядок временного отключения интеграции без остановки всего бизнес-процесса, контакты владельцев внешней системы и правило — какие операции повторять можно, а какие нельзя. Такой документ нужен до запуска в промышленную эксплуатацию, а не после первого инцидента [1].
ADR: как документировать не код, а решения
Отдельная и часто упускаемая часть документации — не то, что система делает сейчас, а почему она устроена именно так. Для этого в разработке применяют практику Architecture Decision Record (ADR) — короткий документ, фиксирующий одно архитектурное решение: контекст, рассмотренные альтернативы, обоснование выбора и последствия [2].
Практическая ценность ADR — не в бюрократии, а в экономии времени команды в будущем: без единого источника истины команды теряют контекст прошлых решений, повторяют старые ошибки и тратят время на восстановление логики выбора [3].
ADR ведут не на каждое решение, а только на архитектурно значимые — те, что влияют на структуру системы или которые трудно отменить, фиксируя контекст, обоснование и последствия принятия решения [4]. Формат простой: короткий markdown-файл рядом с кодом, с полями «контекст», «решение», «альтернативы», «последствия»; есть готовые шаблоны, включая совсем простой четырёхпунктовый вариант Michael Nygard и его расширения вроде MADR.
Российская специфика
ГОСТ 19 ЕСПД: когда обязателен, а когда нет
Единая система программной документации (ЕСПД, серия ГОСТ 19) — комплекс советских, но действующих стандартов, устанавливающих виды программных документов и требования к их оформлению для вычислительных машин и систем независимо от их назначения. Стандарт определяет, какие документы обязательны для программ с самостоятельным применением, а необходимость составления остальных определяется уже на этапе технического задания [5].
На практике полный комплект по ГОСТ 19 в чистом виде для самописного внутреннего модуля почти никогда не нужен — это скорее требование для заказной разработки в госсекторе, для сертификации или для более простого прохождения экспертизы при подаче в реестр отечественного ПО, где заявителю проще опираться на уже знакомый формальный стандарт вместо разработки собственного шаблона документации. Отдельно от ЕСПД для автоматизированных систем в целом используется другая серия — ГОСТ 34, с иным составом разделов.
Реестр отечественного ПО Минцифры: что требуют по документации
Если модуль или платформа со временем становится самостоятельным продуктом и компания планирует включить его в реестр российского ПО, требования к документации становятся формальными и проверяемыми. Минимально нужны: описание функциональных характеристик продукта, системные требования, пошаговая инструкция по установке и инструкция по эксплуатации основных пользовательских сценариев [6].
Отдельное обязательное условие — документация должна быть доступна на русском языке [7]. При проверке заявки эксперты сверяют функциональные возможности продукта именно с приложенной технической документацией, и если описание расходится с реальным функционалом, это повод для дополнительных запросов от Минцифры [8]. Правила реестра периодически меняются — например, поэтапно вводятся требования к подтверждённой совместимости с российскими операционными системами для разных классов ПО, и совместимость должна подтверждаться отдельными документами [9]. Поэтому перед подачей заявки стоит сверяться с актуальной редакцией постановления, а не с общими описаниями двухлетней давности.
Документирование доработок 1С
Для многих российских компаний «самописный модуль» на практике означает доработку 1С или интеграцию 1С с внешним сервисом — банком, маркировкой, госсистемой. У сообщества 1С сложилась устойчивая практика: первое, что нужно освоить при доработке типовой конфигурации, — процесс документирования, потому что без него любой последующий совет по разработке не сработает [10]. Все изменения фиксируют в трекере или базе знаний, дополняя (а не подменяя) информацию из хранилища конфигурации или системы контроля версий, при этом документация не должна вестись «ради документации» и должна своевременно обновляться [10].
Практический смысл этого правила прямой: детальное документирование внесённых изменений позволяет при необходимости сменить разработчика без потери контроля над системой и упрощает последующую доработку и обновление конфигурации [11]. Отдельная особенность 1С — большинство доработок сегодня переносят в механизм расширений, а не в саму типовую конфигурацию, именно чтобы не терять поддержку вендора и не усложнять последующие обновления.
Где хранить документацию: docs-as-code, wiki или ГОСТ-комплект
Формат хранения — вторичный вопрос по отношению к содержанию, но он определяет, будет ли документация актуальной через год. Подход docs-as-code предполагает, что документация хранится рядом с кодом, версионируется вместе с ним и обновляется в том же процессе разработки, что снижает риск расхождения между кодом и описанием, минимизирует ошибки и недопонимания и улучшает коммуникацию между разработчиками и техническими писателями [12]. Для API-контрактов конкретно этот подход означает, что спецификация ведётся в машиночитаемом формате (OpenAPI, AsyncAPI), а не дублируется вручную в отдельной вики-странице — если контракт уже описан формально, в wiki достаточно оставить ссылку на актуальную спецификацию и пояснение, кто её владелец.
Если компании нужен формальный ГОСТ-комплект (для госзаказчика или реестра), разумно вести исходники в markdown или похожем текстовом формате и уже из них собирать финальные документы под требуемый шаблон, а не наоборот — иначе поддерживать актуальность двух параллельных версий документации станет отдельной задачей.
Для читателя документации важно ещё одно: у разных ролей разные вопросы. Аналитику нужны границы обмена и источник истины для данных, разработчику — методы, форматы и коды ошибок, тестировщику — тестовые данные и негативные сценарии, поддержке — runbook, идентификаторы для поиска в логах и контакты владельцев [1]. Один документ редко закрывает все эти вопросы одинаково хорошо, поэтому структуру стоит проектировать под конкретного читателя, а не только под формальное требование «документация должна быть».
Практические этапы внедрения документирования
- Определить, что действительно требует документа. Не каждая функция нуждается в отдельном описании — важны интеграции, влияющие на деньги, персональные данные, отчётность или зависящие от внешнего владельца.
- Зафиксировать контракт до начала разработки, а не после первого рабочего прототипа — иначе документация станет пересказом кода постфактум и быстро устареет.
- Завести ADR с первого архитектурного решения. Первым ADR разумно сделать запись о том, что команда вообще ведёт ADR — это заодно проверяет формат на простом примере.
- Договориться, где хранится документация — рядом с кодом, в общей вики или в виде отдельного ГОСТ-комплекта — и держать один источник истины, а не несколько версий.
- Включить обновление документации в процесс релиза, а не оставлять его на усмотрение конкретного разработчика.
- Проверить актуальность перед передачей на поддержку или сменой исполнителя — на этом этапе обычно и вскрывается, что документация не совпадает с реальным поведением системы.
Ошибки и риски отсутствия документации
- Описан только «счастливый путь» — успешный сценарий, а ошибки, таймауты и повторные отправки остаются недокументированными [1].
- Не указан владелец справочника данных, и при расхождении систем непонятно, чьё значение считать верным.
- Бизнес-отказ и техническая ошибка возвращаются одним и тем же кодом, из-за чего непонятно, нужно ли повторять операцию.
- Изменения в 1С вносятся напрямую в типовую конфигурацию без фиксации, из-за чего очередное обновление платформы стирает доработки или требует ручного переноса вслепую.
- Документация существует, но не обновлялась после последнего релиза — по факту она хуже, чем её полное отсутствие, потому что вводит в заблуждение.
- Знания о системе существуют только в переписке или в голове одного специалиста, и при его уходе восстановить логику решений можно только через анализ кода заново.
Как выбрать нужный уровень документации
Не каждая задача требует полного комплекта. Для внутреннего вспомогательного модуля обычно достаточно README с описанием назначения, входных данных и правил изменения. Для интеграции, влияющей на деньги, статусы заказов или персональные данные, нужен полноценный набор — контракт, словарь данных, ошибки, безопасность и runbook. Для продукта, который планируется подавать в реестр отечественного ПО или поставлять в госсектор, к этому добавляется формальный комплект и документация на русском языке. Не стоит обещать, что сложная разработка документации обязательно нужна там, где хватает уже готового шаблона или короткого README — здесь важнее соразмерность, а не максимальная формализация.
Как может помочь «Пятый фактор»
Основная сложность с документацией самописных модулей и интеграций обычно не в том, чтобы написать текст, а в том, чтобы восстановить логику уже существующей, недокументированной системы, и договориться, какой уровень формализации нужен именно для этой задачи — от короткого README до полного ГОСТ-комплекта под реестр. Команда «Пятого фактора» может изучить существующую интеграцию или доработку, оценить возможные варианты описания архитектуры и данных и помочь с разработкой, интеграцией или технической консультацией.
Вывод
Документирование самописных модулей и интеграций — это не формальность и не разовая задача перед сдачей проекта. Это способ зафиксировать три вещи: что делает система, почему она устроена именно так и что делать, когда она сломается. В российских реалиях к этому добавляются формальные требования — ГОСТ 19 при заказной разработке, документация на русском языке для реестра Минцифры, и отдельная культура фиксации доработок в сообществе 1С. Список требований может показаться избыточным, но на практике все они решают одну и ту же задачу — чтобы знания о системе не терялись вместе с уходом конкретного человека.
Чтобы обсудить задачу или получить консультацию, свяжитесь с командой «Пятого фактора» любым удобным способом.
Источники
[1] robotbull.com — Документирование интеграций и API: что зафиксировать до разработки — https://robotbull.com/handbook/proektirovanie-i-otsenka/dokumentatsiya-dlya-integratsionnogo-proekta
[2] markovpavel.ru — ADR: Architecture Decision Records — зачем и как документировать архитектурные решения — https://markovpavel.ru/proektirovanie/adr-architecture-decision-records-dokumentirovanie-arhitekturnyh-reshenij
[3] habr.com — ADR: Как сохранить архитектурные решения и избежать повторения ошибок — https://habr.com/ru/articles/853862/
[4] learn.microsoft.com — Сохранение записи принятия решений по архитектуре (ADR) — Microsoft Azure Well-Architected Framework — https://learn.microsoft.com/ru-ru/azure/well-architected/architect-role/architecture-decision-record
[5] docs.cntd.ru — ГОСТ 19.101-77 ЕСПД. Виды программ и программных документов — https://docs.cntd.ru/document/1200007627
[6] intellectprava.ru — Регистрация ПО в реестре Российского ПО Минцифры — https://intellectprava.ru/reestr-otechestvennogo-po
[7] cleverence.ru — Как попасть в реестр Минцифры: алгоритм для компаний-разработчиков отечественного ПО — https://www.cleverence.ru/articles/it-i-razrabotka/-kak-popast-v-reestr-mintsifry-algoritm-dlya-kompaniyrazrabotchikov-otechestvennogo-po/
[8] skolkovo-resident.ru — Реестр отечественного ПО: как зарегистрировать программу в 2026 — https://skolkovo-resident.ru/reestr-rossijskogo-po/
[9] zarlaw.ru — Реестр отечественного ПО 2026: новые правила по Постановлению №1937 — https://zarlaw.ru/articles/pravila-vklyucheniya-v-reestr-otechestvennogo-po-i-pak-mintsifry-v-2026-godu-chto-novogo/
[10] iantonov.me — Правильная доработка типовых решений от 1С. Разбираем кейсы легкой поддержки — http://iantonov.me/page/pravilnaja-dorabotka-tipovyh-reshenij-ot-1s-razbiraem-kejsy-legkoj-podderzhki
[11] mp1c.ru — Доработка и развитие конфигураций 1С — https://mp1c.ru/resheniya/uslugi-1c/dorabotka-1c/
[12] documenterra.ru — Docs as code что такое? Примеры успешных и неудачных кейсов — https://documenterra.ru/docs-as-code-podhod-bez-fanatizma/