Как сделать страницу changelog, за которой следят

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

Что такое страница changelog?

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

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

Где должна жить страница changelog?

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

Поддомен — правильный ответ, когда страницу обслуживает система, отличная от маркетингового сайта, и иначе пришлось бы делать proxy. Цена — он накапливает авторитет отдельно. Размещение changelog в документации правильно, когда аудитория — разработчики, по причине, разобранной в changelog API: читатель там уже обычно находится.

Важнее выбора то, что на записи можно ссылаться по отдельности. Люди ссылаются на записи в разборах инцидентов и внутренних тикетах, и запись, на которую можно сослаться только как “changelog, прокрутите вниз”, вместо этого вклеивается скриншотом.

Что нужно странице changelog?

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

Остальное опционально. Скриншоты помогают и требуют поддержки. Имена авторов создают доверие в одних продуктах и шум в других. Номера версий важны для вызывающих API и почти ни для кого больше. Keep a Changelog — разумный выбор по умолчанию для меток, если у вас нет причин изобретать свои, и его центральное правило стоит сохранить, даже если отбросить остальное: журнал пишется для людей.

Группируйте по дате, а не по версии, если ваш продукт релизится непрерывно. Читатель, сканирующий “это было до или после нашего инцидента девятого числа”, ищет дату, а страница, организованная по номеру версии, заставляет его считать.

Страница или виджет в приложении?

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

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

Как сделать страницу changelog машиночитаемой?

Публикуйте те же записи как поток. JSON-поток — вариант с наименьшим трением для всего, что потребляет его в коде, а RSS-поток — то, чего ожидает разработчик, подписавшийся в ридере. Оба обходятся дёшево, как только записи становятся структурированными данными вместо HTML, написанного вручную, что и есть реальный аргумент за то, чтобы держать каноническую копию структурированной.

Разметьте и страницу тоже. Записи — это произведения с датой и заголовком, и schema.org предоставляет словарь. Это стоит сделать по той же причине, что и постоянные ссылки: это делает страницу пригодной для использования вещами, которые не являются браузером, включая собственный процесс релизов клиента. Ничего из этого не работает, если исходные записи никогда не были структурированными данными с самого начала; форматы файлов changelog разбирает, сколько стоит каждый из Markdown, JSON и YAML как источник истины, из которого этот поток и эта разметка реально генерируются.

Помогает ли страница changelog SEO?

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

Что не работает — это относиться к записям как к контент-маркетингу. Запись, раздутая до трёх абзацев ради длины, хуже справляется со своей настоящей работой — сказать читателю в одном предложении, изменилось ли что-то, чем он пользуется. Если хотите, чтобы changelog поддерживал поиск, вкладывайте усилия в постоянные ссылки, поток и внутренние ссылки на него, а записи держите короткими. Наша собственная страница примеров changelog собирает страницы, которые верно ловят этот баланс.

Как люди подписываются?

Дайте им пути, которыми они уже пользуются: RSS- или JSON-поток для разработчиков, email для тех, кто хочет слышать только важное, и виджет в приложении для всех, кто никогда не сделает ни того ни другого. Спрашивайте, что они хотят слышать, а не предполагайте, потому что читатель, желающий breaking changes и получающий исправления текста, отписывается от обоих.

Путь, который стоит добавить последним, — тот, что замыкает петлю. Когда запись решает то, о чём попросил конкретный человек, скажите ему это напрямую, вместо того чтобы надеяться, что он прочтёт страницу. В changeloop запись публикуется сразу на странице, в потоке и виджете, и человека, чей отзыв из виджета стал GitHub issue, закрытым этим pull request, оповещают в этом issue со ссылкой на запись, и он видит запись в виджете. Механизм тот же, что и у любой подписки; разница в том, что получатель уже спросил. Это аргумент, развёрнутый в закрытии петли обратной связи со стороны changelog.

FAQ

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

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

Стоит ли когда-нибудь удалять старые записи? Нет. На них ссылаются извне вашего сайта, и ссылки ломаются. Исправляйте запись на месте с пометкой, и держите URL живым.

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

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

По теме на changeloop: Примеры changelog, Документация для разработчиков