Jak zbudować stronę changeloga, którą się śledzi

Stronę changeloga warto zbudować, gdy ktoś by na nią wracał. To wyższa poprzeczka niż samo jej posiadanie, i to poprzeczka, na której zawodzi większość: strona, która istnieje, jest linkowana w stopce, aktualizowana zrywami i odwiedzana przez nikogo poza incydentem. Decyzje rozdzielające te dwie zapadają, zanim cokolwiek zostanie napisane, i dotyczą głównie tego, gdzie mieszka strona i co jeszcze jest generowane z tej samej treści.

Czym jest strona changeloga?

To publiczna, datowana lista tego, co zmieniło się w produkcie, pod adresem URL, który należy do was. To jedna z pięciu powierzchni, na których mogą pojawiać się te same wpisy, a przydatne pytanie to nie które wybrać, ale które jest kanoniczne i które z niego są generowane.

Wybierzcie jedno kanoniczne źródło, opublikujcie raz, i generujcie resztę. Zespoły utrzymujące stronę i widżet osobno ręcznie kończą z dwoma tekstami, które się nie zgadzają, a rozbieżność odkrywa klient.

Gdzie powinna mieszkać strona changeloga?

Na waszej własnej domenie, pod stabilną ścieżką, z każdym wpisem indywidualnie adresowalnym. Trzy powszechne lokalizacje to ścieżka na głównej stronie, subdomena i sekcja dokumentacji. Ścieżka na głównej stronie to domyślny wybór, przeciwko któremu należy argumentować, nie za nim: dziedziczy autorytet strony, nie wymaga dodatkowego certyfikatu ani DNS, i utrzymuje stronę w tej samej nawigacji co wszystko inne.

Subdomena to właściwa odpowiedź, gdy stronę obsługuje inny system niż strona marketingowa i inaczej robilibyście proxy. Koszt jest taki, że gromadzi autorytet osobno. Umieszczenie changeloga w dokumentacji jest właściwe, gdy odbiorcami są deweloperzy, z powodu omówionego w changelog API: czytelnik zwykle już tam jest.

Ważniejsze niż wybór jest to, żeby wpisy dało się linkować indywidualnie. Ludzie linkują wpisy w analizach incydentów i wewnętrznych zgłoszeniach, a wpis, do którego można linkować tylko jako “changelog, przewiń w dół”, ląduje wklejony jako zrzut ekranu.

Czego potrzebuje strona changeloga?

Pięciu rzeczy, i na pierwszych dwóch zawodzi większość stron. Datowany wpis na zmianę, najnowszy pierwszy. Kategoria lub etykieta na wpis, żeby móc skanować pod kątem interesującego typu. Permalink na wpis. Ścieżka subskrypcji. Wyszukiwanie lub filtr po około pięćdziesięciu wpisach.

Reszta jest opcjonalna. Zrzuty ekranu pomagają i kosztują utrzymania. Nazwiska autorów budują zaufanie w niektórych produktach i są szumem w innych. Numery wersji liczą się dla wywołujących API i prawie nikogo innego. Keep a Changelog to rozsądny domyślny wybór etykiet, jeśli nie macie powodu wymyślać własnych, a jego centralna zasada jest tą, którą warto zachować, nawet jeśli odrzucicie resztę: dziennik jest pisany dla ludzi.

Grupujcie według daty, nie wersji, gdy wasz produkt wydaje w sposób ciągły. Czytelnik skanujący “czy to było przed czy po naszym incydencie dziewiątego” szuka daty, a strona zorganizowana według numeru wersji zmusza go do liczenia.

Strona czy widżet w aplikacji?

Oba, z jednego źródła. Strona to miejsce, gdzie mieszkają wyszukiwanie, linki i długi rejestr. Widżet to sposób, w jaki docieracie do większości użytkowników, którzy nigdy nie odwiedzą strony, i działa, bo pojawia się w produkcie, którego już używają.

Porażka widżetu to przerwanie. Odznaka wymagająca uwagi przy każdym wpisie zostaje trwale odrzucona w ciągu tygodnia, co kosztuje was kanał dla wpisu, który naprawdę się liczył. Liczcie nieprzeczytane od ostatniego spojrzenia czytelnika, zasiewajcie licznik po cichu przy pierwszej wizycie, żeby nikt nie był witany odznaką roku historii, i pozwólcie czytelnikowi ją otworzyć zamiast otwierać ją za niego.

Jak zrobić stronę changeloga czytelną maszynowo?

Publikujcie te same wpisy jako strumień. Strumień JSON to opcja o najniższym tarciu dla wszystkiego, co konsumuje go w kodzie, a strumień RSS to to, czego oczekuje deweloper subskrybujący w czytniku. Oba kosztują mało, gdy wpisy są danymi strukturalnymi zamiast ręcznie pisanym HTML-em, co jest prawdziwym argumentem za utrzymaniem kanonicznej kopii ustrukturyzowanej.

Oznaczcie stronę też. Wpisy to utwory z datą i tytułem, a schema.org dostarcza słownictwa. Warto to zrobić z tego samego powodu co permalinki: to sprawia, że strona jest użyteczna dla rzeczy, które nie są przeglądarką, w tym własnego procesu wydawniczego klienta. Nic z tego nie działa, jeśli leżące u podstaw wpisy nigdy nie były danymi strukturalnymi od początku; formaty plików changeloga ujmuje, ile kosztuje każdy z Markdown, JSON i YAML jako źródło prawdy, z którego ten strumień i te znaczniki są faktycznie generowane.

Czy strona changeloga pomaga SEO?

Pośrednio i powoli. Pojedyncze wpisy rzadko się pozycjonują, bo nie celują w żadne zapytanie, które ktoś wpisuje. Strona zdobywa swoje miejsce przez linki: wpisy są cytowane w odpowiedziach supportu, na forach i w analizach incydentów, a te linki gromadzą się na adresie URL, który należy do was. Strona aktualizowana co tydzień przez dwa lata to też wiarygodny sygnał świeżości dla produktu, do którego należy.

To, co nie działa, to traktowanie wpisów jak content marketingu. Wpis nadmuchany do trzech akapitów dla długości jest gorszy w swojej prawdziwej pracy, czyli powiedzeniu czytelnikowi w jednym zdaniu, czy coś, czego używa, się zmieniło. Jeśli chcecie, żeby changelog wspierał wyszukiwanie, włóżcie wysiłek w permalinki, strumień i linki wewnętrzne do niego, i trzymajcie wpisy krótkie. Nasza własna strona przykładów changeloga zbiera strony, które trafiają w tę równowagę dobrze.

Jak ludzie się subskrybują?

Dajcie im ścieżki, których już używają: strumień RSS lub JSON dla deweloperów, e-mail dla tych, co chcą słyszeć tylko ważne rzeczy, i widżet w aplikacji dla wszystkich, którzy nigdy nie zrobią żadnego z tych dwóch. Pytajcie, co chcą słyszeć, zamiast to zakładać, bo czytelnik chcący zmian łamiących, a dostający poprawki tekstu, wypisuje się z obu.

Ścieżkę, którą warto dodać na końcu, to ta, która zamyka pętlę. Gdy wpis rozwiązuje coś, o co prosiła konkretna osoba, powiedzcie jej to bezpośrednio, zamiast liczyć, że przeczyta stronę. W changeloop wpis publikuje się jednocześnie na stronie, w strumieniu i widżecie, a osoba, której opinia z widżetu stała się zgłoszeniem na GitHubie zamkniętym przez pull request, jest informowana w tym zgłoszeniu z linkiem do wpisu i widzi ten wpis w widżecie. Mechanizm jest taki sam jak każda subskrypcja; różnica jest taka, że odbiorca już zapytał. To argument rozwinięty w zamykaniu pętli feedbacku od strony changeloga.

FAQ

Czy strona changeloga powinna być na subdomenie czy ścieżce? Domyślnie ścieżka na głównej stronie, bo dziedziczy autorytet strony i nie wymaga dodatkowej infrastruktury. Subdomena jest uzasadniona, gdy stronę obsługuje inny system.

Ile wpisów powinna pokazywać strona naraz? Tyle, żeby wypełnić ekran, i nie więcej, z paginacją potem. Ładowanie dwóch lat historii do jednego dokumentu jest wolne i utrudnia znalezienie najnowszego wpisu.

Czy stare wpisy powinny być kiedykolwiek usuwane? Nie. Są cytowane spoza waszej strony, a linki się łamią. Poprawcie wpis w miejscu z notatką, i utrzymujcie adres URL przy życiu.

Czy każda zmiana musi pojawić się na stronie? Tylko te, które użytkownik mógłby zauważyć. Strona rejestrująca wewnętrzne refaktoryzacje uczy czytelników pobieżnego czytania, a pobieżnie czytana strona zawodzi w dniu, gdy niesie coś pilnego.

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: Przykłady changeloga, Dokumentacja dla deweloperów