Документация существующего сайта: как описать систему, чтобы её можно было поддерживать

Документация существующего сайта — это описание текущей архитектуры, доработок и интеграций проекта. Она нужна, чтобы передача проекта, поддержка и развитие не зависели от памяти одного человека. Ниже — что фиксировать, как собирать сведения и как принять документ.

Зачем бизнесу документация существующего сайта и где её границы

Документация существующего сайта фиксирует текущее состояние проекта, а не изначальные замыслы. За годы эксплуатации решения устаревают, появляются доработки и внешние сервисы. Без фиксации этих данных передача проекта превращается в долгое расследование.

Документ решает практические задачи:

• новый специалист быстрее входит в проект и не ломает работающие узлы;
• руководитель видит структуру сайта и зоны ответственности;
• при смене подрядчика не нужно восстанавливать историю решений;
• при сбое понятно, к какому сервису обращаться.

Границы задачи стоит очертить сразу, иначе документ разрастётся. Документация существующего сайта не заменяет ТЗ на новую разработку, не описывает код и не дублирует официальную документацию платформы. Учебные курсы, FAQ и видеоматериалы — это внешние источники, на которые нужно ссылаться. Внутри документа остаётся только то, что относится к вашему проекту.

Отдельная граница — юридическая. Упоминание персональных данных, согласий, сроков хранения или реквизитов требует сверки с юристом. Техническая документация фиксирует, где и какие данные обрабатываются, но правовую оценку даёт специалист.

Карта систем и зависимостей: с чего начинается описание

Карта систем и зависимостей — обязательный артефакт, с которого начинается описание. Она показывает состав проекта и связи между узлами. Без неё непонятно, где заканчивается сайт и начинается внешний сервис.

На карту наносят:

• публичную часть сайта и административный раздел;
• базу данных как отдельный узел;
• внешние сервисы: приём платежей, расчёт доставки, рассылки, аналитика, системы учёта;
• интеграции с учётными системами и обмен данными;
• сервер или хостинг, домены, DNS, сертификаты;
• резервное копирование и место хранения копий.

Для каждой связи фиксируют направление обмена, тип данных, владельца сервиса и последствия обрыва связи. Это превращает схему из картинки в инструмент диагностики.

Как читать карту неспециалисту

Карта должна быть понятна неспециалисту. Рядом с каждым узлом дают короткое пояснение: что это и зачем нужно бизнесу. Например, узел «служба доставки» поясняется как «считает стоимость и срок доставки при оформлении заказа». Это позволяет руководителю участвовать в обсуждении без погружения в детали.

Что делать с узлами без владельца

Если у сервиса нет ответственного, это риск. Узел помечают отдельно и выносят в список вопросов: кто продлевает подписку, кто видит ошибки, к кому идти при отказе. Документация существующего сайта ценна тем, что вскрывает такие пробелы.

Как описать нестандартные функции и интеграции

Типовые возможности платформы описывать не нужно — на них есть официальная документация. Фиксируют доработки под конкретный проект. Эти места чаще всего ломаются при обновлениях и их сложнее всего восстановить по памяти.

Для каждой доработки в документе указывают:

• какую задачу она решает и кто её поставил;
• где она видна в интерфейсе — в публичной части или в административном разделе;
• какие данные использует и откуда их берёт;
• кто отвечает за работу функции;
• как проверить, что она работает;
• что произойдёт при сбое и как это заметить.

Отдельный блок — интеграции. Обмен с учётной системой, приём платежей, расчёт доставки, фискализация, рассылки. По каждой интеграции фиксируют, что синхронизируется, с какой периодичностью, кто видит ошибки и куда они попадают. Если интеграция работает через посредника, это тоже отмечают: при сбое важно понимать, на чьей стороне искать причину.

Как выявить кастомизацию

Прежде чем описывать доработки, их нужно найти. Инвентаризация начинается с выявления изменений относительно типового решения. Составляют перечень отклонений от стандартной поставки, затем собирают описание. Такой порядок не даёт пропустить забытые правки, оставшиеся в проекте.

Что писать про настройки сайтов

Если проект использует несколько сайтов на одном ядре, в документе перечисляют их и указывают параметры: домен, папку, язык, региональные настройки, признак сайта по умолчанию. Сведения берут из административного раздела. Полезно зафиксировать порядок сортировки сайтов: при размещении на поддомене он влияет на корректное открытие, это стоит перепроверить.

Связь документации с версиями проекта

Документ без привязки к версии быстро устаревает. У описания есть версия, дата и краткая запись об изменениях. При обновлении проекта документ обновляют сразу, а не «когда-нибудь потом».

Практичный приём — журнал изменений. В нём построчно: дата, что поменялось, кто внёс, где смотреть результат. Журнал не заменяет подробное описание, но помогает понять логику текущей версии. Если доработка отменена, запись помечают как неактуальную: история решений часто нужнее.

Ещё одна связка — соответствие описания среде. Если есть тестовый контур, в документе отмечают отличия настроек от рабочего. Это снижает риск, что проверка на тесте пройдёт, а на рабочем сайте поведение окажется другим.

Какие исходные данные подготовить для оценки

Чтобы оценить объём работ по документации, исполнителю нужен входной набор. Чем полнее он собран заранее, тем точнее оценка.

• Перечень сайтов и доменов, включая поддомены и сайты на том же ядре.
• Список внешних сервисов и интеграций с указанием, кто ими пользуется.
• История доработок: задачи, переписка, описания правок, если они сохранились.
• Сведения о том, кто отвечает за проект со стороны бизнеса и со стороны подрядчика.
• Данные о резервном копировании: делается ли оно, где хранятся копии, кто проверяет восстановление.
• Описание ролей: кто из сотрудников что делает в административном разделе.

Доступы передают по согласованному безопасному каналу и в объёме, достаточном для работы. Пароли и ключи не вставляют в текст документации: там указывают, где они хранятся и кто имеет к ним доступ. Это снижает риск утечки и упрощает смену ответственных.

Если проект уже сопровождается, часть сведений логично взять из действующего регламента поддержки. Понять, что обычно входит в такой регламент, помогает материал Что входит в техническую поддержку сайта — его удобно использовать как ориентир при сборе исходных данных.

Практический пример: описание тестового проекта

Учебный пример. Данные условные и приведены только для иллюстрации порядка действий и структуры описания.

Входные условия. Условная компания торгует через сайт на Битрикс. На одном ядре работают два сайта: основной магазин и небольшой информационный раздел на поддомене. Есть обмен с учётной системой, приём платежей и расчёт доставки через внешний сервис. За время эксплуатации проект дорабатывался: появился нестандартный калькулятор доставки и отдельная форма заявки. Ответственный за сайт со стороны бизнеса — один сотрудник, который согласует правки.

Действия.

1. Составляют карту систем и зависимостей: два сайта, база данных, учётная система, платёжный сервис, служба доставки, хостинг, резервное копирование. 2. Проводят инвентаризацию доработок и выявляют отклонения от типового решения. 3. По каждому отклонению описывают задачу, место в интерфейсе, используемые данные и способ проверки. 4. Фиксируют параметры обоих сайтов: домены, папки, язык, региональные настройки, порядок сортировки. 5. Описывают интеграции: что и как часто синхронизируется, кто видит ошибки. 6. Заводят журнал изменений и указывают, кто отвечает за актуальность документа.

Наблюдаемый результат. Появляется документ, по которому новый специалист может понять устройство проекта, не поднимая историю переписки. Видны узлы без ответственного и места, где проверка не описана. Руководитель получает основу для постановки задач на развитие.

Проверка. Документ считают готовым, если по нему можно ответить на вопросы: из чего состоит проект, что доработано, где это видно, как проверить работу и к кому обращаться при сбое. Полезный приём — попросить человека, не знакомого с проектом, найти по документу конкретную функцию и описать, как её проверить.

Как проверить результат и принять работу

Приёмка документации — это не чтение «на глаз», а проверка по чек-листу вопросов. Ниже — рабочий чек-лист.

• Карта систем и зависимостей есть, и на ней отмечены все внешние сервисы и интеграции.
• У каждого узла карты указан ответственный или явно помечено, что его нет.
• Перечислены доработки относительно типового решения, и по каждой указано место в интерфейсе.
• Для каждой доработки описан способ проверки и поведение при сбое.
• Интеграции описаны с указанием направления обмена, периодичности и того, кто видит ошибки.
• Параметры сайтов зафиксированы: домены, папки, язык, региональные настройки, порядок сортировки.
• Есть журнал изменений и указан ответственный за актуальность документа.
• Пароли и ключи в тексте не хранятся, указано только место их хранения и владелец доступа.
• Отмечены места, требующие сверки с юристом: обработка персональных данных, состав согласий, реквизиты.
• Документ проверен человеком, не знакомым с проектом: он смог найти функцию и описать её проверку.

Если хотя бы один пункт чек-листа не выполняется, документ возвращают на доработку. Это дешевле, чем разбираться с последствиями на рабочем сайте.

Типичные ошибки и ограничения

Ошибки в документации существующего сайта повторяются из проекта в проект.

• Описание задуманного вместо фактического. Документ рассказывает, как проект планировали, а не как он работает. Читатель вводится в заблуждение.
• Пересказ официальной документации. Вместо ссылки на внешний источник в файл копируют общие сведения о продукте. Такой текст быстро устаревает и не относится к проекту.
• Отсутствие версии. Непонятно, к какому состоянию проекта относится описание.
• Пароли в тексте. Учётные данные хранят отдельно, а в документе указывают только место хранения и владельца.
• Описание без способа проверки. Если не сказано, как убедиться, что функция работает, документ бесполезен при диагностике.
• Один ответственный без замены. Если человек уходит, актуальность документа никто не поддерживает.

Ограничения метода тоже стоит назвать честно. Документация не гарантирует отсутствие сбоев и не заменяет резервное копирование. Она не отменяет необходимость тестировать изменения перед выкаткой на рабочий сайт. И она не даёт юридического заключения по обработке данных — это отдельная зона ответственности.

Что дальше

Собранная документация — не финальная точка, а рабочий инструмент. Дальше её поддерживают: обновляют при доработках, дополняют при подключении новых сервисов, пересматривают при смене ответственных. Если проект передаётся на сопровождение, документ становится частью передачи. Понять, как обычно выстроена такая работа и что в неё входит, помогает материал поддержка сайта на Битрикс. А если предстоит оценить объём сопровождения, полезно заранее посмотреть, из чего складывается стоимость и какие варианты бывают, — об этом в статье Сколько стоит поддержка сайта на Битрикс: тарифы и что входит.