Как обосновать решение

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

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

Коротко:

Карточку пишут на развилку, а не на каждый пункт технического задания и не на цвет темы.
Требование говорит, что нужно. Карточка говорит, какой способ выбрали и почему отвергли остальные.
В разделе «почему» каждый отвергнутый вариант проигрывает по названному критерию. Слова «популярный» и «лучший» такими критериями не являются.
Отказ от функции, которую уже просили, записывают той же карточкой, что и выбор платформы.
«Когда пересмотреть» — событие, которое организация заметит. Дата в календаре таким событием не считается.
Пустая клетка «почему» при заполненных остальных значит, что решение ещё не принято.
Заменённую карточку не удаляют: помечают «заменена» и ссылаются на новую.

Требование и карточка

В главе о выборе функций список задач превращается в требования. Хорошее требование говорит, что нужно, и его можно проверить: «национальный портал забирает описания в профиле DCAT-AP». Название платформы и расширения в требовании — уже решение, его принимают следующим шагом.

Карточка — этот шаг. На то же требование она отвечает: «ставим ckanext-dcat с профилем DCAT-AP 3, свой экспорт не пишем». Полная карточка про выгрузку — в главе об экспорте метаданных. Цепочки от задачи до платформы — в разобранных примерах.

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

На какие развилки её пишут

Развилка	Зачем карточка	Где разобрано
Способ создания: свой портал, чужой каталог, статический сайт, своя разработка	способов несколько, и ошибка дорогая	муниципалитет, ведомство с двадцатью наборами, квартальная таблица, главный адрес на своей странице, массив снимков, каталог, который ведут двое
Платформа	в коротком списке больше одной	регион и университет
Расширение, без которого обязательная функция не работает	в ядре этой функции нет	выгрузка DCAT
Отказ от функции, которую уже просили	иначе через год её поставят как забытую	отказ от DOI, город копирует большой портал
Обновление ядра, когда расширение на новую версию не проверено	на кону вход публикаторов и исправления безопасности	обновление ядра
Своя разработка	ни одна готовая платформа не закрывает обязательную функцию	свой маркетплейс
Два каталога вместо одного	две задачи плохо живут в одной программе	статслужба, регион с картами
Какой уровень качества чинить первым	иначе редакция заполняет карточки пустых файлов	«поднять качество»
Как публиковать: форма, скрипт или файл для сборщика	каталог отстаёт от системы, в которой данные уже есть	наборы уже лежат в системе
Какую лицензию писать в поле	свой текст и известная лицензия спорят, или закрытый файл помечен как открытый	свой текст или известная лицензия

Мелочи карточки не требуют: тема, цвета, подписи кнопок. Не требуют и пункты минимума, против которых никто не спорил, — постоянный адрес и сама привычка ставить лицензию на набор. Карточка появляется, когда кто-то предложил обойтись без них или заменить известную лицензию своим текстом.

Городу часто хватает одной карточки. Региону нужны карточки на платформу, на сборку расширений и на отказы. Двадцать карточек до запуска значат, что в них попали настройки.

Шаблон

Приём пришёл из разработки программ. В 2011 году Майкл Найгард описал короткую запись решения: контекст, само решение, последствия — в том числе неприятные — и пометку, если решение потом заменили. Запись пишут для человека, который придёт позже, на одну-две страницы, и хранят рядом с тем, к чему она относится. Заменённую не стирают.

Для каталога к этому добавлены сравнение и условие пересмотра. Сравнение нужно, потому что выбирают между продуктами: без отвергнутых вариантов разделу «почему» не к чему приложить. Условие пересмотра называют заранее, потому что повод обычно приходит извне — сменится профиль страны, грант или версия ядра, — и ждать, пока это заметят задним числом, уже поздно.

Раздел	Что писать
Контекст	факты, которые тянут в разные стороны: задача, ограничение, уже стоящая система
Варианты	два-четыре варианта, которые правда рассматривали
Критерии	по чему сравнивали и какой критерий важнее, если они спорят
Решение	что выбрано, одной фразой, с именами платформы и расширений
Почему	по какому критерию проиграл каждый отвергнутый вариант
Последствия	что получаем и чем платим
Когда пересмотреть	событие, после которого карточку открывают заново

В главах о возможностях карточки иногда короче: плату там уже назвал окружающий текст. Карточка, которая лежит рядом с договором, включает все семь разделов.

Как звучит раздел, который можно проверить

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

Раздел	Так обычно пишут	Так можно проверить
Контекст	Хотим современный портал	Регион уже на CKAN. Национальный портал забирает описания в DCAT-AP. Своей команды нет, есть подрядчик
Варианты	Рассмотреть лучшие решения	ckanext-dcat; свой экспорт силами подрядчика; ручная выгрузка раз в квартал
Критерии	Популярность, удобство, цена	Файл совпадает с профилем, который ждёт национальный портал. Кто чинит экспорт при смене профиля. Можно ли обновить CKAN
Решение	Надёжная открытая платформа	ckanext-dcat с профилем DCAT-AP
Почему	CKAN популярный	Расширение ведёт сообщество CKAN и уже умеет этот профиль. Свой экспорт станет ещё одной программой на балансе подрядчика. Ручная выгрузка отстанет в первый же месяц
Последствия	Портал станет лучше	При каждом обновлении CKAN подрядчик проверяет расширение. В ядре CKAN этой выгрузки нет, и это штатная сборка
Когда пересмотреть	Через пять лет или при необходимости	Национальный портал сменит профиль, или расширение перестанут выпускать под новую версию CKAN

Популярность иногда стоит за настоящим критерием: «в стране есть подрядчики, которые уже сопровождают текущую версию CKAN и ckanext-dcat». Тогда в карточку попадает эта фраза. Слово «популярный» само по себе сверить не с чем.

Контекст пишут фактами, без оценки. «Подрядчик может написать экспорт, и экспорт останется его программой» — факт. «Свой экспорт — плохая идея» — вывод, ему место в разделе «почему».

Варианты называют конкретно: имя расширения, чужой каталог, статический сайт с файлом data.json. «Более простой путь» вариантом не является. Слабый ход, которого никто не предлагал и который вставлен, чтобы победитель выглядел очевидным, портит карточку: следующий читатель не отличит его от настоящего отказа. Если смотрели только один вариант, так и пишут. Карточка тогда показывает, что сравнения не было, и это тоже полезная запись.

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

Решение — одна фраза с именами. «CKAN с ckanext-dcat» — решение. «Современная открытая платформа» — пожелание.

Раздел «почему» сравнивает. На каждый отвергнутый вариант приходится фраза, по какому критерию он проиграл. Похвала выбранному без этой фразы повторяет решение другими словами. Пустая клетка при заполненных остальных значит, что выбор ещё не сделан.

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

«Когда пересмотреть» — событие, которое заметят без повторного чтения обоснования. Национальный портал сменил профиль. Расширение не вышло под новую версию ядра. Наборов стало больше числа, которое назвали заранее. Появилась ставка на сопровождение. Грант потребовал DOI. Рядом одной фразой — что тогда делают, если это уже ясно: «закрываем свой CKAN и переносим адреса». Если ход ещё не ясен, карточка говорит открыть вопрос заново. Новое решение — новая карточка, а не правка задним числом.

«Через пять лет», «при необходимости», «когда изменится технология» и «на следующей закупке» событием не являются: в нужный день их никто не заметит. Календарная дата уместна, когда она стоит в чужом документе, и тогда в карточке назван этот документ.

Пример отказа от DOI

Это карточка к строке «DOI — не нужно» из таблицы требований природоохранного ведомства. Образец записи, не ответ для любого портала.

Контекст. Ведомство публикует ежечасные замеры качества воздуха и разрешения на выбросы. Границы охраняемых территорий уже лежат на региональном геопортале. Национальный портал забирает описания в DCAT-AP. Исследователь просит DOI, «как у научных порталов». Договора с DataCite нет. Портал предполагают ставить на CKAN.

Варианты. Выдавать DOI на каждый набор расширением ckanext-doi. Выдавать DOI только проверенному годовому архиву, если его начнут публиковать, через Zenodo или библиотеку. Обойтись постоянным адресом набора и файла.

Критерии. Совпадает ли обещание ссылки с тем, как меняются данные. Проверено ли расширение на той версии CKAN, которую поставят. Нужен ли ведомству договор с DataCite.

Решение. DOI не выдавать. У набора и файла — постоянный адрес и дата обновления.

Почему. Замеры меняются каждый час. DOI обещает зафиксированное состояние, а открывал бы сегодняшние данные. ckanext-doi на CKAN 2.11 и 2.12 не тестировался, это записано в главе про CKAN. Договор с DataCite ради оперативных рядов ведомству не нужен. Годовой архив для статей — другая публикация, в научном репозитории, и на неё будет отдельная карточка, когда архив появится.

Последствия. Кнопки DOI на портале нет. Письмо исследователю закрывают постоянным адресом и датой выгрузки. В ответе прямо сказано, что DOI этот портал не выдаёт.

Когда пересмотреть. Ведомство начнёт выпускать проверенный годовой архив, на который ссылаются в статьях. Тогда решают, где у архива DOI, и не включают его на этом портале молча.

Пример обновления ядра

Карточка к ситуации из главы про CKAN: новая версия ядра вышла, а расширение, без которого портал не пускает публикаторов, на ней не проверено. Факты о расширениях сверены 13 октября 2026 года. Это образец записи, не предписание всем министерствам.

Контекст. Портал министерства на CKAN 2.11. Сотрудники входят ведомственной учётной записью через ckanext-saml2auth. Последний выпуск этого расширения — 1.3.0 от 14 декабря 2022 года, в нём заявлена поддержка CKAN 2.10. Автоматические тесты идут на 2.10 и 2.11, на 2.12 их нет. CKAN 2.12 вышел 26 августа 2026 года, и проект называет его последним выпуском линейки 2.x. Версия 2.11 пока получает исправления ошибок и безопасности. Когда поддерживаемой парой станут более новые выпуски, 2.11 этих исправлений лишится. Подрядчик предлагает обновиться.

Варианты. Остаться на 2.11, пока ckanext-saml2auth не проверят на 2.12. Перейти на 2.12, заранее проверив вход на тестовом стенде. Сменить расширение на ckanext-saml: выпуск 0.4.1 от 2 июня 2026 года содержит исправление под изменения SQLAlchemy в CKAN 2.12, автоматических тестов у расширения нет.

Критерии. В день перехода публикаторы входят. Портал не остаётся без исправлений безопасности на неопределённый срок. Проверка идёт на стенде, не на боевом сайте.

Решение. Подрядчик поднимает стенд CKAN 2.12 с текущим ckanext-saml2auth и проверяет вход сотрудника. Если вход работает, переносят боевой портал. Если нет, на том же стенде пробуют ckanext-saml 0.4.1. Пока ни один вариант вход не проходит, боевой портал остаётся на 2.11.

Почему. Строка в журнале изменений не заменяет вход сотрудника: ckanext-saml поправил одну несовместимость и не показывает тестов на 2.12. Остаться на 2.11 без срока значит пропустить исправления безопасности, когда 2.11 выпадет из поддерживаемой пары. Менять расширение в день обновления, без стенда, оставляет портал без публикаторов.

Последствия. В работу по обновлению заложен стенд. В карточке записан адрес репозитория, который ставят: у ckanext-saml и ckanext-saml2auth разные команды и разная доказательная база. Если оба на стенде не пускают, обновление не откладывают молча: сразу открывают новую карточку о том, чем заменить вход.

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

Если расширение перестанут выпускать

Эту развилку записывают в тот день, когда расширение ставят, а не в тот, когда оно замолчит. В разделе «когда пересмотреть» или в последствиях называют один из трёх ходов:

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

Ход выбирают по тому, обязательна ли функция. Выгрузку, которую забирает национальный портал, снять нельзя: ищут замену или остаются на старом ядре, пока это безопасно. Кнопку цитирования снять можно: постоянный адрес и дата обращения остаются. Как оценивать само расширение — в главе об экосистемах.

Где лежит карточка и кто её пишет

Карточку пишет тот, кто выбирает, до подписания договора или до установки. Запись после запуска обычно защищает уже сделанное.

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

Комитет для этого не нужен. Нужна одна страница, которую откроет человек через три года.

Как проверить свою карточку

Типичные ошибки

Одна карточка на всю закупку. Платформа, цвет шапки, DOI и подрядчик в одном тексте. Через год нельзя заменить одно, не переписывая всё. Развилки разделяют.
Критерии из брошюры. «Удобный, современный, масштабируемый» выполняет любой участник сравнения. Критерий привязан к вашей задаче: профиль, который ждёт национальный портал, вход сотрудников, кто чинит расширение.
Чужая карточка. Соседи выбрали CKAN с тремя расширениями, потому что собирают сотню муниципалитетов. Городу с тридцатью наборами это чужое обязательство и чужая плата.
Вариант для вида. В список вставлен заведомо слабый ход, которого никто не предлагал. Настоящие отвергнутые варианты из карточки исчезают.
Последствия только про пользу. Плату обнаруживают при первом обновлении ядра.
Дата вместо события. «Вернуться в 2031 году» не говорит, что изменилось. Календарь уместен как срок чужого обязательства, и тогда в карточке назван документ.
Карточка задним числом. Её пишут, чтобы обосновать уже подписанный договор. Варианты подбираются под победителя.
Старую карточку удалили. Новый сотрудник видит текущий портал и не видит, какое обязательство сняли при замене.

Источники

Michael Nygard, Documenting Architecture Decisions, 15 ноября 2011 года — короткая запись решения: контекст, решение, последствия, в том числе неприятные; заменённую запись оставляют и помечают.
Принципы выбора набора функций — чем требование отличается от решения.
От функций к платформе, разобранные примеры, свои силы, свободное ПО или облачный сервис.
Экспорт метаданных — карточка про выгрузку DCAT.
CKAN: ядро и расширения — версии ядра и ckanext-doi; доступ, роли и процессы — расширения входа.
ckanext-dcat.
Выпуск ckanext-saml2auth 1.3.0 от 14 декабря 2022 года; журнал изменений ckanext-saml, выпуск 0.4.1 от 2 июня 2026 года. Сверено 13 октября 2026 года.
Политика выпусков CKAN; объявление CKAN 2.12 от 26 августа 2026 года — 2.12 назван последним выпуском линейки 2.x.
Экосистемы расширений — как оценивать расширение до того, как записать его в карточку.

Требование и карточка​

На какие развилки её пишут​

Шаблон​

Как звучит раздел, который можно проверить​

Пример отказа от DOI​

Пример обновления ядра​

Если расширение перестанут выпускать​

Где лежит карточка и кто её пишет​

Как проверить свою карточку​

Типичные ошибки​

Источники​