Jak psát release notes, které lidé skutečně čtou

Chcete-li psát release notes, které lidé čtou, odpovězte v každém záznamu na jedinou otázku: co teď čtenář může udělat, co předtím nemohl, a co s tím musí udělat. Dejte na první místo vše s termínem, pojmenujte, koho se to týká, napište «není potřeba žádná akce», když je to pravda, a přeskočte vydání, která nemají co říct. Vše ostatní na této stránce je aplikace tohoto pravidla.

Opravy chyb a vylepšení výkonu.

Každý produkt to jednou zveřejnil. Příčinou je jen zřídka lenost: takhle to dopadá, když se release notes píší zevnitř, někým, kdo strávil dva týdny v diffu a už nevidí, které části by zajímaly cizího člověka. Lepší tón to nevyřeší; odpověď na otázku ano.

Co by měly release notes obsahovat?

Release notes by měly u každé změny, která si zaslouží zmínku, obsahovat: co teď čtenář může udělat, koho se to týká, co s tím musí udělat (včetně «nic»), a kdy vstoupí v platnost cokoli s termínem. Neměly by obsahovat čísla interních ticketů, názvy komponent, které používá jen tým, ani číslo verze jako jediný titulek.

Rozdíl mezi release note a záznamem changelogu je to, co tento seznam umožňuje: changelog uchovává vše, takže poznámky mohou něco vynechat. Komentované vzorky každého druhu záznamu jsou sebrány v článku příklady release notes.

Otázka, na kterou odpovídá každý záznam

Co teď čtenář může udělat, co předtím nemohl, a co s tím musí udělat?

Pokud záznam na to nedokáže odpovědět, patří do changelogu, ne do release notes. Obě poloviny záleží. První polovina je hodnota. Druhá polovina je ta, na kterou týmy zapomínají, a je to ta, která generuje tickety do podpory, když chybí.

Dva příklady druhé poloviny, která odvádí skutečnou práci:

• «Existující webhooky budou fungovat do 1. listopadu. Po tomto datu budou nepodepsané payloady odmítnuty.»
• «Není potřeba žádná akce. Existující exporty se automaticky překódují při příštím otevření.»

Druhý výslovně říká «není potřeba žádná akce». Tuto větu stojí za to psát pokaždé, protože čtenář, který ji nenajde, předpokládá to nejhorší.

Jak by měly být release notes uspořádány?

Uspořádejte je podle důsledků pro čtenáře, nikdy podle části systému, která se změnila. Seskupení podle API, panelu, mobilu a infrastruktury je vaše organizační schéma, ne problém čtenáře.

1. Breaking changes a vše s termínem. Vždy jako první, i když je to drobnost. Pokud čtenář přestane číst po jednom řádku, měl by to být ten řádek. Pokud je termín sunset, záznam by měl znít jako oznámení o deprekaci.
2. Co je nové a co budou chtít. Jedno na odstavec, s výsledkem v první větě.
3. Co se zlepšilo. Nahlášené chyby, zvýšené limity, věci, které byly pomalé.
4. Vše ostatní, jako seznam. Aktualizace závislostí, interní refaktoring, drobný text. Po jednom řádku každé. Tuto sekci nikdo nečte, a přesto tam musí být, protože kdo ji hledá, ji skutečně potřebuje.

Přepis

Před:

v4.2.0 Opravena chyba, kdy endpoint POST /exports občas vracel 500 pod zátěží. Refaktorován export worker. Aktualizován node-pg na 8.11. Vylepšeno zpracování chyb v CSV serializátoru.

Po:

Exporty už na velkých účtech neselhávají. Účty s více než přibližně 50 000 řádky mohly při spuštění exportu dostat 500, častěji na konci měsíce. To je opraveno, a exporty jakékoli velikosti se nyní samy opakují místo selhání. Není potřeba žádná akce, a jakýkoli export, který selhal minulý týden, lze jednoduše spustit znovu.

Také ve 4.2.0: node-pg 8.11, jasnější chyby v CSV serializátoru.

Stejné vydání. Druhý pojmenovává postižený účet, okamžik, kdy to bylo nejhorší, co se změnilo, a co dělat. Aktualizace závislosti nezmizela, jen přestala být titulkem. Článek nejlepší praktiky pro release notes obsahuje zbytek pravidel, kterými se tento přepis řídí, každé s cenou za jeho vynechání.

Věci, které stojí za odstranění

• «S radostí oznamujeme.» Čtenář ještě není nadšený. Zasloužte si to v další větě.
• Interní čísla ticketů. PROJ-4471 mimo váš tracker nic neznamená. Pokud záznam potřebuje odkaz, odkažte na stránku dokumentace.
• Názvy komponent, které používá jen váš tým. Pokud jste přejmenovali «ingest pipeline», řekněte «importy».
• Číslo verze jako jediný titulek. v4.2.0 je archivační štítek, ne shrnutí.
• Snímky obrazovky stránky nastavení, kterou nikdo nenavštívil. Ukažte to, co se změnilo, v použití.

Jak často by se měly release notes zveřejňovat?

Zveřejňujte, když se něco stalo, ne podle harmonogramu. Poznámky, které přicházejí s každým vydáním, učí všechny je ignorovat. Poznámky, které přicházejí, když se něco stalo, se otevírají. Je v pořádku, a obvykle správné, vydat release bez jakékoli poznámky a jeho záznamy přesunout do další sady, která má titulek stojící za přečtení.

Changelog nadále zaznamenává vše. To je dělba práce: changelog je úplný, poznámky jsou selektivní. Pokud udržujete changelog strukturovaný průběžně, psaní poznámek se stává výběrem a přepisem, ne archeologií.

Šablona release notes je forma, kterou používáme pro fázi výběru, a příklady changelogu shromažďuje záznamy od týmů, jejichž changelog je dostatečně dobrý na to, aby se z něj daly odvodit poznámky.

Tohle všechno předpokládá stránku, kterou plně kontrolujete, bez limitu délky a s fungujícími odkazy. Release notes pro mobilní aplikace rozebírá, co se mění, když je povrchem výpis v App Store nebo Play Store. Pohotovostní release notes rozebírají druhou výjimku: co se mění, když nezbývá vůbec čas sledovat běžný proces psaní.

Jeden test před zveřejněním

Přečtěte si poznámky jako někdo, kdo byl dva týdny na dovolené a má 40 sekund. Pokud za tu dobu nedokáže poznat, zda se od něj něco žádá, poznámky nejsou hotové, ať jsou sebepřesnější.

FAQ

Jak dlouhé by měly být release notes? Tak dlouhé, jak vyžadují změny s důsledky, a ani o řádek víc. Vydání s jednou breaking change a dvěma vylepšeními jsou tři odstavce. Naplnění tichého vydání, aby vypadalo podstatně, je způsob, jak se čtenáři učí poznámky přeskakovat.

Kdo by měl psát release notes? Osoba, která rozumí změně, upravená někým, kdo jí nerozumí. Inženýrka ví, co se změnilo; redaktorka ví, co cizí člověk pochopí špatně. Psaní záznamu v okamžiku merge, dokud si to inženýrka ještě pamatuje, je praxe, díky které je to levné.

Měly by release notes obsahovat opravy chyb? Ano, ty, které někdo nahlásil nebo na ně narazil. Uveďte symptom, který viděl čtenář, ne příčinu. «Exporty nad 50 000 řádků selhávaly» je oprava, kterou čtenář pozná; «opravena race condition v export workeru» je zpráva commitu.

Jaký je rozdíl mezi release notes a changelogem? Changelog je úplný, průběžný záznam; release notes jsou vybraná zpráva o jednom vydání, napsaná pro lidi, kteří se ještě nerozhodli, jestli je to zajímá. Delší odpověď je v changelog vs release notes.

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: Šablona poznámek k vydání, Příklady changelogu