Jak postavit changelog stránku, kterou lidé sledují

Changelog stránku se vyplatí postavit, když by se na ni lidé vraceli. To je vyšší laťka než mít ji prostě jen tak, a je to laťka, na které selhává většina: stránka, která existuje, je odkazovaná v patičce, aktualizuje se v nárazech a nenavštěvuje ji nikdo kromě doby incidentu. Rozhodnutí, která tyto dva případy odlišují, padají dřív, než se cokoli napíše, a jsou hlavně o tom, kde stránka žije a co jiného se generuje ze stejného obsahu.

Co je changelog stránka?

Je to veřejný, datovaný seznam toho, co se v produktu změnilo, na URL, která patří vám. Je to jeden z pěti povrchů, na kterých se mohou objevit stejné záznamy, a užitečná otázka není, který vybrat, ale který je kanonický a které jsou z něj generované.

Vyberte jeden kanonický zdroj, publikujte jednou, a zbytek generujte. Týmy, které udržují stránku a widget odděleně ručně, skončí se dvěma texty, které se neshodují, a rozpor objeví klient.

Kde by měla changelog stránka žít?

Na vaší vlastní doméně, na stabilní cestě, s každým záznamem individuálně adresovatelným. Tři běžná umístění jsou cesta na hlavním webu, subdoména, a sekce dokumentace. Cesta na hlavním webu je výchozí volba, proti které je třeba argumentovat, ne pro ni: dědí autoritu webu, nepotřebuje další certifikát ani DNS, a drží stránku ve stejné navigaci jako všechno ostatní.

Subdoména je správná odpověď, když stránku obsluhuje jiný systém než marketingový web a jinak byste dělali proxy. Cenou je, že hromadí autoritu odděleně. Umístění changelogu do dokumentace je správné, když publikem jsou vývojáři, z důvodu probraného v API changelog: čtenář je tam obvykle už tak jako tak.

Důležitější než volba je, že záznamy musí být individuálně odkazovatelné. Lidé odkazují na záznamy v rozborech incidentů a interních tiketech, a záznam, na který lze odkázat jen jako “changelog, scrollujte dolů”, skončí místo toho vložený jako snímek obrazovky.

Co potřebuje changelog stránka?

Pět věcí, a na prvních dvou selhává většina stránek. Datovaný záznam na změnu, nejnovější první. Kategorie nebo štítek na záznam, aby šlo skenovat podle zajímavého typu. Permalink na záznam. Cesta k odběru. Vyhledávání nebo filtr po zhruba padesáti záznamech.

Zbytek je volitelný. Snímky obrazovky pomáhají a stojí údržbu. Jména autorů budují důvěru u některých produktů a jsou šum u jiných. Čísla verzí záleží volajícím API a téměř nikomu jinému. Keep a Changelog je rozumná výchozí volba pro štítky, pokud nemáte důvod vymýšlet vlastní, a jeho ústřední pravidlo je to, které stojí za zachování, i když zbytek zahodíte: deník je psaný pro lidi.

Seskupujte podle data, ne podle verze, když váš produkt vydává průběžně. Čtenář, který skenuje “bylo tohle před nebo po našem incidentu devátého”, hledá datum, a stránka organizovaná podle čísla verze ho nutí počítat.

Stránka nebo widget v aplikaci?

Obojí, z jednoho zdroje. Stránka je místo, kde žije vyhledávání, odkazy a dlouhý záznam. Widget je způsob, jak oslovit většinu uživatelů, kteří stránku nikdy nenavštíví, a funguje, protože se objevuje v produktu, který už používají.

Selhání widgetu je přerušení. Odznak, který vyžaduje pozornost u každého záznamu, je do týdne trvale odmítnut, což vás stojí kanál pro záznam, na kterém opravdu záleželo. Počítejte nepřečtené od posledního pohledu čtenáře, tiše zasejte počítadlo při první návštěvě, aby nikoho nepřivítal odznak s rokem historie, a nechte čtenáře, ať si ho otevře sám, místo abyste mu ho otevírali vy.

Jak udělat changelog stránku strojově čitelnou?

Publikujte stejné záznamy jako feed. JSON feed je možnost s nejmenším třením pro cokoli, co ho konzumuje v kódu, a RSS feed je to, co očekává vývojář odebírající ve čtečce. Oba stojí málo, jakmile jsou záznamy strukturovaná data místo ručně psaného HTML, což je skutečný argument pro udržení kanonické kopie strukturované.

Označte i stránku. Záznamy jsou díla s datem a titulkem, a schema.org poskytuje slovník. Vyplatí se to ze stejného důvodu jako permalinky: dělá to stránku použitelnou pro věci, které nejsou prohlížeč, včetně vlastního release procesu klienta. Nic z tohohle nefunguje, pokud podkladové záznamy nikdy nebyly strukturovaná data od začátku; formáty souborů changelogu pokrývá, kolik stojí každý z Markdown, JSON a YAML jako zdroj pravdy, ze kterého se tenhle feed a tenhle markup skutečně generují.

Pomáhá changelog stránka SEO?

Nepřímo a pomalu. Jednotlivé záznamy se málokdy umístí, protože necílí na žádný dotaz, který někdo zadá. Stránka si své místo vydělá přes odkazy: záznamy jsou citovány v odpovědích supportu, na fórech a v rozborech incidentů, a tyto odkazy se hromadí na URL, která patří vám. Stránka aktualizovaná týdně po dva roky je také důvěryhodným signálem svěžesti pro produkt, ke kterému patří.

Co nefunguje, je zacházet se záznamy jako s content marketingem. Záznam nafouknutý na tři odstavce kvůli délce je horší ve své skutečné práci, což je říct čtenáři v jedné větě, jestli se něco, co používá, změnilo. Pokud chcete, aby changelog podporoval vyhledávání, vložte úsilí do permalinků, feedu a interních odkazů na něj, a záznamy nechte krátké. Naše vlastní stránka příkladů changelogu sbírá stránky, které tuto rovnováhu trefují dobře.

Jak se lidé odebírají?

Dejte jim cesty, které už používají: RSS nebo JSON feed pro vývojáře, e-mail pro ty, kdo chtějí slyšet jen důležité věci, a widget v aplikaci pro všechny, kdo neudělají nikdy ani jedno z toho. Ptejte se, co chtějí slyšet, místo abyste to předpokládali, protože čtenář, který chce breaking changes a dostává textové opravy, se odhlásí od obou.

Cesta, kterou se vyplatí přidat jako poslední, je ta, která uzavírá smyčku. Když záznam vyřeší něco, o co konkrétní člověk požádal, řekněte mu to přímo, místo abyste doufali, že si přečte stránku. V changeloop se záznam publikuje najednou na stránce, feedu a widgetu, a člověk, jehož zpětná vazba z widgetu se stala GitHub issue, které pull request uzavřel, je informován v tom issue s odkazem na záznam a vidí ten záznam ve widgetu. Mechanismus je stejný jako u jakéhokoli odběru; rozdíl je, že příjemce už se zeptal. To je argument rozvinutý v uzavření smyčky zpětné vazby ze strany changelogu.

FAQ

Měla by changelog stránka být na subdoméně, nebo na cestě? Ve výchozím stavu cesta na hlavním webu, protože dědí autoritu webu a nepotřebuje další infrastrukturu. Subdoména je oprávněná, když stránku obsluhuje jiný systém.

Kolik záznamů by měla stránka zobrazovat najednou? Dost na naplnění obrazovky a ne víc, pak stránkování. Načítání dvou let historie do jednoho dokumentu je pomalé a ztěžuje nalezení nejnovějšího záznamu.

Měly by se staré záznamy někdy mazat? Ne. Jsou citovány zvenčí vašeho webu a odkazy se rozbijí. Opravte záznam na místě s poznámkou, a udržujte URL naživu.

Musí se každá změna objevit na stránce? Jen ty, které by uživatel mohl zaznamenat. Stránka, která zaznamenává interní refaktoring, trénuje čtenáře, aby text jen přelétli, a přelétnutá stránka selže v den, kdy nese něco naléhavého.

Technická tvrzení v tomto článku nikdo nezávisle neověřil. Pokud tu něco nesedí, dej nám vědět a opravíme to.

Související na changeloop: Příklady changelogu, Dokumentace pro vývojáře