Awaryjne release notes: pisanie pod prawdziwą presją
5 min czytania
Większość release notes jest pisana po tym, jak kod jest gotowy, spokojnie sprawdzana i publikowana według harmonogramu, który nie ma nic wspólnego z tym, jak pilnie ktoś musi je przeczytać. Wydanie awaryjne, łatka bezpieczeństwa, błąd utraty danych, naprawa awarii, odwraca wszystkie te warunki naraz: notatki muszą istnieć, zanim większość ludzi normalnie zaczęłaby je pisać, otrzymują prawie żadną recenzję, i są czytane przez ludzi, którzy są zaniepokojeni zamiast spokojni. Jak pisać release notes opisuje normalny proces; to jest o tym, co się zmienia, gdy nie zostaje czas, by go przejść.
Co awaryjna release note musi koniecznie zrobić dobrze, jeśli nic innego?
Czy czytelniczka musi coś zrobić, powiedziane w pierwszym zdaniu, bez żadnego kontekstu przed tym. Czytelniczka trafiająca na release note wywołaną incydentem jest często już zaniepokojona, usłyszawszy o problemie ze strony statusu, wątku wsparcia, lub od własnych użytkowniczek, a notatka, która zaczyna się od kontekstu przed elementem akcji, czyta się jako zatrzymywanie informacji dokładnie w okolicznościach, w których zatrzymywanie czyta się najgorzej. “Nie jest wymagane żadne działanie, to łata lukę, która nie wymagała danych użytkownika do wykorzystania” i “Zaktualizujcie natychmiast: to wydanie naprawia błąd, który mógł pokazywać dane jednego konta innemu” to obie jedno zdanie, i obie wykonują całą pracę, której potrzebuje spanikowana czytelniczka, zanim przeczyta cokolwiek innego.
Czy zwykły przebieg edycji nadal obowiązuje, gdy nie ma na niego czasu?
Instynkt kompresji przetrwa, nawet gdy proces wielu wersji roboczych, który go zwykle wytwarza, nie przetrwa. Przepisanie opisuje ucinanie rozwlekłej pierwszej wersji do jej istotnego zdania; pod presją czasu często nie ma pierwszej wersji do ucięcia, co oznacza, że dyscyplina musi działać w waszej głowie podczas pisania, zamiast jako osobny przebieg potem. Najszybszy sposób, by się do niej zbliżyć: napiszcie zdanie, które powiedzielibyście na głos komuś pytającemu “co muszę wiedzieć”, potem przestańcie, ponieważ to zdanie jest zwykle zarówno najszybsze do wyprodukowania, jak i jedyne, które czytelniczka w tym stanie faktycznie przetworzy.
| Normalna release note | Awaryjna release note |
|---|---|
| Pisana po code review, przed publikacją | Często pisana razem z poprawką, przed pełną recenzją |
| Zoptymalizowana pod skanowalność wielu wpisów | Zoptymalizowana pod jeden wpis czytany w izolacji, pod stresem |
| Może odłożyć szczegóły do połączonego changelogu | Powinna postawić na czele jeden najważniejszy fakt |
| Kontekst i tło są mile widziane | Kontekst przed elementem akcji czyta się jako zwłoka |
Czy kiedykolwiek jest w porządku opublikować notatkę, zanim jest się całkowicie pewnym, co spowodowało problem?
Tak, jeśli notatka jest szczera co do tej niepewności zamiast sugerować pewność, której nie macie. “Wdrożyliśmy poprawkę na podwyższone wskaźniki błędów przy płatności; wciąż potwierdzamy główną przyczynę i zaktualizujemy tę notatkę” jest obronialne i poprawnie kupuje czas; notatka, która stwierdza konkretną przyczynę, której faktycznie nie potwierdziliście, to rodzaj domysłu, który staje się tym, co ludzie wam później zacytują, jeśli okaże się błędny. Dyscyplina, która tu się liczy, to nie szybkość diagnozy, to nigdy niepozwalanie, by pewność notatki przekroczyła rzeczywistą pewność zespołu, ponieważ błędne twierdzenie techniczne w awaryjnej notatce wyrządza więcej szkody zaufaniu niż przyznana niewiadoma.
Zbyt pewny, niezweryfikowany:
"Fixed: a race condition in the payment webhook handler
caused duplicate charges."
Szczery pod presją czasu:
"Naprawiono: niektórym klientkom naliczono podwójną
opłatę za jedno zamówienie. Zatrzymaliśmy nowe
wystąpienia i zwracamy pieniądze dotkniętym kontom w
ciągu 24 godzin. Badamy główną przyczynę."Czy awaryjna notatka powinna mówić, co spowodowało problem, czy tylko że został naprawiony?
Powiedzcie, co jest naprawione i co powinna zrobić czytelniczka; zachowajcie główną przyczynę na kontynuację, gdy będzie naprawdę znana, nie domyślona. Czytelniczka w środku incydentu chce dokładnie dwóch faktów, czy to jest rozwiązane i czy mnie dotyczy, a wyjaśnienie głównej przyczyny, nawet dokładne, konkuruje z tymi dwoma faktami o uwagę w najgorszym możliwym momencie, by ją stracić. Post-mortem, publikowany osobno po zakończeniu dochodzenia, to miejsce, gdzie należy główna przyczyna; mieszanie tych dwóch dokumentów pod presją czasu produkuje notatkę wolniejszą do napisania i wolniejszą do przeczytania, przeciwieństwo tego, czego potrzebuje sytuacja awaryjna.
Czy problem wymuszonej aktualizacji z aplikacji mobilnych dotyczy też tutaj?
Ta sama zasada, jeszcze bardziej skompresowana. Release notes dla aplikacji mobilnych opisuje wymuszone aktualizacje, gdzie notatka musi podać powód i termin przed czymkolwiek, ponieważ czytelniczka jest już zirytowana brakiem wyboru; awaryjna release note w sieci jest zwykle opt-in dla czytelniczki w tym sensie, że wybiera, czy na nią zareagować, ale ten sam instynkt “najpierw podaj ograniczenie” obowiązuje, tylko z innego powodu: nie irytacja, pilność.
Jak uniknąć, by awaryjna notatka czytała się jak przyznanie się do winy, gdy nie powinna?
Opiszcie poprawkę i jej efekt, nie winę, i oprzyjcie się pokusie nadmiernych przeprosin, co czyta się jako wypełniacz dla czytelniczki, która chce dwóch faktów powyżej. “Znaleźliśmy i naprawiliśmy błąd wpływający na niektóre eksporty” mówi, co się stało, bez przypisywania temu dramatu; “Jest nam niezwykle przykro z powodu tego poważnego problemu, który dotknął naszych cenionych klientek” opóźnia użyteczną informację o całe zdanie, by dostarczyć emocjonalny moment, o który czytelniczka nie prosiła. Krótka, rzeczowa notatka nie jest zimna, szanuje rzeczywisty stan czytelniczki, który pod prawdziwą presją to niecierpliwość, nie potrzeba pocieszenia.
FAQ
Czy awaryjna release note powinna przejść przez ten sam proces recenzji co normalna? Lżejszy, nie żaden: jedna szybka recenzentka sprawdzająca, że notatka nie przesadza z pewnością, jest warta tych kilku minut, które kosztuje, ponieważ ryzyko, że niesprawdzone twierdzenie techniczne jest błędne, jest wyższe właśnie dlatego, że zostało napisane szybko.
Czy w porządku jest opublikować awaryjną notatkę bez żadnego linku do dalszych szczegółów? Tylko krótko. Notatka bez linku działa jako pierwsza rzecz opublikowana; dodajcie go do strony statusu lub kontynuacji, gdy tylko jedno z nich zaistnieje, ponieważ czytelniczka chcąca więcej niż jednego zdania, które jej daliście, potrzebuje gdzieś pójść, nawet jeśli to miejsce mówi “więcej szczegółów wkrótce”.
Czy awaryjna notatka powinna być kiedykolwiek całkowicie pominięta, pozwalając poprawce wyjść po cichu? Tylko przy problemach, których żadna czytelniczka nie mogłaby zauważyć ani być nimi dotknięta; jeśli istnieje jakakolwiek szansa, że czytelniczka doświadczyła problemu, notatka jest tym, co mówi jej, że to się skończyło, a cisza czyta się jakby problem mógł wciąż być aktywny.
Jak długo awaryjna notatka powinna pozostać przypięta lub widoczna po rozwiązaniu incydentu? Aż zamknie się okno bezpośredniego niepokoju, typowo dzień lub dwa, wtedy może zwinąć się w normalny changelog jak każdy inny wpis; notatka pozostająca przypięta tygodniami zaczyna czytać się jako nierozwiązana obawa zamiast rozwiązanej.
Twierdzenia techniczne w tym artykule nie zostały niezależnie zweryfikowane. Jeśli coś się nie zgadza, daj nam znać, a poprawimy to.