Jak pisać release notes, które ludzie faktycznie czytają

Żeby napisać release notes, które ludzie czytają, odpowiedz na jedno pytanie w każdym wpisie: co czytelnik może teraz zrobić, czego wcześniej nie mógł, i co musi w związku z tym zrobić. Umieść na początku wszystko z terminem, wskaż, kogo to dotyczy, powiedz “żadne działanie nie jest wymagane”, gdy to prawda, i pomiń wydania, które nie mają nic do powiedzenia. Wszystko inne na tej stronie to zastosowanie tej reguły.

Poprawki błędów i usprawnienia wydajności.

Każdy produkt kiedyś to opublikował. Przyczyną rzadko jest lenistwo: to wynik pisania release notes od środka, przez kogoś, kto spędził dwa tygodnie w diffie i nie widzi już, które fragmenty obchodziłyby kogoś z zewnątrz. Lepszy ton tego nie naprawi; odpowiedź na pytanie tak.

Co powinny zawierać release notes?

Release notes powinny zawierać, dla każdej zmiany wartej wzmianki: co czytelnik może teraz zrobić, kogo to dotyczy, co musi zrobić (w tym “nic”), i kiedy wchodzi w życie coś z terminem. Nie powinny zawierać wewnętrznych numerów ticketów, nazw komponentów używanych tylko przez zespół, ani numeru wersji jako jedynego nagłówka.

Podział między release note a wpisem changelogu jest tym, co czyni tę listę możliwą: changelog przechowuje wszystko, więc notatki mogą coś pomijać. Opisane przykłady każdego rodzaju wpisu zebrano w przykładach release notes.

Pytanie, na które odpowiada każdy wpis

Co czytelnik może teraz zrobić, czego wcześniej nie mógł, i co musi w związku z tym zrobić?

Jeśli wpis nie może na to odpowiedzieć, należy do changelogu, a nie do release notes. Obie połowy mają znaczenie. Pierwsza połowa to wartość. Druga połowa to ta, o której zapominają zespoły, i to ona generuje zgłoszenia do wsparcia, gdy jej brakuje.

Dwa przykłady drugiej połowy wykonującej prawdziwą pracę:

• “Istniejące webhooki będą nadal działać do 1 listopada. Po tej dacie niepodpisane payloady zostaną odrzucone.”
• “Żadne działanie nie jest wymagane. Istniejące eksporty zostaną automatycznie przekodowane przy następnym otwarciu.”

Drugi wprost mówi “żadne działanie nie jest wymagane”. To zdanie warto pisać za każdym razem, ponieważ czytelnik, który go nie znajdzie, założy najgorsze.

Jak powinny być uporządkowane release notes?

Uporządkuj je według konsekwencji dla czytelnika, nigdy według części systemu, która się zmieniła. Grupowanie według API, panelu, mobilnej wersji i infrastruktury to wasz schemat organizacyjny, nie problem czytelnika.

1. Zmiany łamiące kompatybilność i wszystko z terminem. Zawsze na pierwszym miejscu, nawet jeśli to drobiazg. Jeśli czytelnik przestaje czytać po jednej linii, to właśnie ją musiał przeczytać. Jeśli termin to sunset, wpis powinien brzmieć jak powiadomienie o deprecjacji.
2. Co nowego, na co będą czekać. Jeden na akapit, z rezultatem w pierwszym zdaniu.
3. Co się poprawiło. Zgłoszone błędy, podniesione limity, rzeczy, które były wolne.
4. Wszystko inne, jako lista. Aktualizacje zależności, wewnętrzne refaktoryzacje, drobne teksty. Po jednej linii każde. Nikt tej sekcji nie czyta, a mimo to musi tam być, bo kto jej szuka, naprawdę jej potrzebuje.

Przepisanie

Przed:

v4.2.0 Naprawiono problem, przez który endpoint POST /exports sporadycznie zwracał 500 pod obciążeniem. Zrefaktoryzowano workera eksportu. Zaktualizowano node-pg do 8.11. Ulepszono obsługę błędów w serializatorze CSV.

Po:

Eksporty nie zawodzą już na dużych kontach. Konta z ponad około 50 000 wierszy mogły otrzymać 500 przy rozpoczynaniu eksportu, częściej pod koniec miesiąca. To zostało naprawione, a eksporty dowolnego rozmiaru teraz same próbują ponownie zamiast zawodzić. Żadne działanie nie jest wymagane, a każdy eksport, który zawiódł w zeszłym tygodniu, można po prostu uruchomić ponownie.

Także w 4.2.0: node-pg 8.11, jaśniejsze błędy w serializatorze CSV.

To samo wydanie. Drugi wskazuje dotknięte konto, moment, w którym było najgorzej, co się zmieniło i co zrobić. Aktualizacja zależności nie zniknęła, po prostu przestała być nagłówkiem. Artykuł najlepsze praktyki release notes zawiera resztę reguł, za którymi podąża to przepisanie, każda z kosztem jej pominięcia.

Rzeczy warte usunięcia

• “Z radością ogłaszamy.” Czytelnik jeszcze nie jest zadowolony. Zdobądź to w następnym zdaniu.
• Wewnętrzne numery ticketów. PROJ-4471 nic nie znaczy poza waszym trackerem. Jeśli wpis potrzebuje odniesienia, podlinkuj stronę dokumentacji.
• Nazwy komponentów używane tylko przez wasz zespół. Jeśli zmieniliście nazwę “pipeline ingestu”, powiedzcie “importy”.
• Numer wersji jako jedyny nagłówek. v4.2.0 to etykieta archiwizacyjna, nie podsumowanie.
• Zrzuty ekranu strony ustawień, której nikt nigdy nie odwiedził. Pokaż to, co się zmieniło, w użyciu.

Jak często powinny być publikowane release notes?

Publikuj, gdy coś się wydarzyło, nie według harmonogramu. Notatki, które przychodzą przy każdym wydaniu, uczą wszystkich je ignorować. Notatki, które przychodzą, gdy coś się wydarzyło, są otwierane. W porządku jest, i zwykle jest to słuszne, wydać release bez żadnej notatki i przenieść jego wpisy do następnego zestawu, który ma nagłówek wart przeczytania.

Changelog nadal rejestruje wszystko. Taki jest podział pracy: changelog jest kompletny, notatki są selektywne. Jeśli utrzymujecie changelog uporządkowany na bieżąco, pisanie notatek staje się selekcją i przepisywaniem, a nie archeologią.

Szablon release notes to forma, której używamy do etapu selekcji, a przykłady changelogu zbiera wpisy zespołów, których changelog jest wystarczająco dobry, by wyprowadzić z niego notatki.

To wszystko zakłada stronę, którą w pełni kontrolujesz, bez limitu długości i z działającymi linkami. Release notes dla aplikacji mobilnych opisuje, co się zmienia, gdy powierzchnią jest wpis w App Store albo Play Store. Awaryjne release notes opisuje inny wyjątek: co się zmienia, gdy w ogóle nie zostaje czas, by przejść normalny proces pisania.

Jeden test przed publikacją

Przeczytaj notatki jak ktoś, kto był na urlopie przez dwa tygodnie i ma 40 sekund. Jeśli w tym czasie nie może powiedzieć, czy coś jest od niego wymagane, notatki nie są gotowe, niezależnie od tego, jak dokładne są.

FAQ

Jak długie powinny być release notes? Tak długie, jak wymagają tego zmiany z konsekwencjami, i ani linii dłużej. Wydanie z jedną zmianą łamiącą kompatybilność i dwoma usprawnieniami to trzy akapity. Wypełnianie cichego wydania, żeby wyglądało na znaczące, to sposób, w jaki czytelnicy uczą się pomijać notatki.

Kto powinien pisać release notes? Osoba, która rozumie zmianę, redagowana przez kogoś, kto jej nie rozumie. Inżynierka wie, co się zmieniło; redaktorka wie, co ktoś z zewnątrz źle zrozumie. Pisanie wpisu w momencie merge’a, gdy inżynierka jeszcze pamięta, to praktyka, która czyni to tanim.

Czy release notes powinny zawierać poprawki błędów? Tak, te, które ktoś zgłosił lub napotkał. Podaj objaw widziany przez czytelnika, nie przyczynę. “Eksporty powyżej 50 000 wierszy zawodziły” to poprawka, którą czytelnik rozpoznaje; “naprawiono race condition w workerze eksportu” to komunikat commita.

Jaka jest różnica między release notes a changelogiem? Changelog to kompletny, ciągły rejestr; release notes to wyselekcjonowana wiadomość o jednym wydaniu, napisana dla ludzi, którzy jeszcze nie zdecydowali, czy ich to obchodzi. Dłuższa odpowiedź jest w changelog vs release notes.

Twierdzenia techniczne w tym artykule nie zostały niezależnie zweryfikowane. Jeśli coś się nie zgadza, daj nam znać, a poprawimy to.

Powiązane w changeloop: Szablon notatek wydania, Przykłady changeloga