Cum construiești o pagină de changelog care se urmărește

O pagină de changelog merită construită dacă cineva ar reveni la ea. Este o ștachetă mai înaltă decât a o avea pur și simplu, și e ștacheta la care majoritatea eșuează: o pagină care există, are link în footer, se actualizează în salturi și nu e vizitată de nimeni în afară de timpul unui incident. Deciziile care despart cele două se iau înainte ca ceva să fie scris, și țin mai ales de unde locuiește pagina și ce altceva se generează din același conținut.

Ce este o pagină de changelog?

Este lista publică și datată a ceea ce s-a schimbat la un produs, la o adresă URL care vă aparține. Este una din cinci suprafețe pe care pot apărea aceleași intrări, iar întrebarea utilă nu e pe care o alegi, ci care e canonică și care sunt generate din ea.

Alegeți o sursă canonică, publicați o dată, și generați restul. Echipele care mențin pagina și widget-ul separat, manual, ajung cu două texte care nu se potrivesc, iar discrepanța o descoperă un client.

Unde ar trebui să locuiască o pagină de changelog?

Pe propriul vostru domeniu, pe o cale stabilă, cu fiecare intrare adresabilă individual. Cele trei amplasări comune sunt o cale pe site-ul principal, un subdomeniu, și o secțiune a documentației. O cale pe site-ul principal e alegerea implicită împotriva căreia trebuie argumentat, nu în favoarea ei: moștenește autoritatea site-ului, nu are nevoie de certificat sau DNS suplimentar, și menține pagina în aceeași navigare cu tot restul.

Un subdomeniu e răspunsul corect când pagina e servită de un sistem diferit de site-ul de marketing și altfel ați face proxy. Costul e că acumulează autoritate separat. A pune changelog-ul în documentație e corect când publicul e format din dezvoltatori, din motivul acoperit în changelog de API: cititorul e de obicei deja acolo.

Mai important decât alegerea e ca intrările să poată fi legate individual. Oamenii leagă intrări în analize de incidente și tichete interne, iar o intrare care poate fi legată doar ca “changelog-ul, derulează în jos” ajunge lipită ca o captură de ecran în schimb.

De ce are nevoie o pagină de changelog?

Cinci lucruri, iar la primele două eșuează majoritatea paginilor. O intrare datată per schimbare, cea mai nouă întâi. O categorie sau etichetă per intrare pentru a putea scana după tipul care interesează. Un permalink per intrare. O cale de abonare. O căutare sau filtru după aproximativ cincizeci de intrări.

Restul e opțional. Capturile de ecran ajută și costă întreținere. Numele autorilor construiesc încredere la unele produse și sunt zgomot la altele. Numerele de versiune contează pentru apelanții unui API și pentru aproape nimeni altcineva. Keep a Changelog e o alegere implicită rezonabilă pentru etichete dacă nu aveți motiv să inventați propriile voastre, iar regula lui centrală e cea de păstrat chiar dacă renunțați la rest: jurnalul e scris pentru oameni.

Grupați după dată, nu după versiune, când produsul vostru lansează continuu. Un cititor care scanează “a fost asta înainte sau după incidentul nostru din nouă” caută o dată, iar o pagină organizată după numărul de versiune îl obligă să facă socoteli.

Pagină sau widget în aplicație?

Ambele, dintr-o singură sursă. Pagina e locul unde locuiesc căutarea, linkurile și jurnalul lung. Widget-ul e felul în care ajungeți majoritatea utilizatorilor care nu vor vizita niciodată pagina, și funcționează pentru că apare în produsul pe care îl folosesc deja.

Eșecul widget-ului e întreruperea. Un badge care cere atenție pentru fiecare intrare e respins permanent într-o săptămână, ceea ce vă costă canalul pentru intrarea care chiar a contat. Numărați necititele de la ultima privire a cititorului, semănați contorul în tăcere la prima vizită astfel încât nimeni să nu fie întâmpinat cu un badge al unui an de istorie, și lăsați cititorul să-l deschidă în loc să-l deschideți voi pentru el.

Cum faci o pagină de changelog lizibilă de mașini?

Publicați aceleași intrări ca flux. Un flux JSON e opțiunea cu cea mai mică fricțiune pentru orice îl consumă din cod, iar un flux RSS e ce așteaptă un dezvoltator abonat într-un reader. Ambele costă puțin odată ce intrările sunt date structurate în loc de HTML scris de mână, ceea ce e argumentul real pentru a păstra copia canonică structurată.

Marcați și pagina. Intrările sunt opere cu dată și titlu, iar schema.org oferă vocabularul. Merită făcut din același motiv ca permalinkurile: face pagina utilizabilă de lucruri care nu sunt un browser, inclusiv propriul proces de lansare al unui client. Nimic din astea nu funcționează dacă intrările de bază nu au fost niciodată date structurate de la început; formate de fișier pentru changelog acoperă cât costă fiecare din Markdown, JSON și YAML ca sursă de adevăr din care acest flux și acest marcaj sunt de fapt generate.

Ajută o pagină de changelog la SEO?

Indirect și încet. Intrările individuale se clasează rar, pentru că nu vizează nicio interogare pe care o tastează cineva. Pagina își câștigă locul prin linkuri: intrările sunt citate în răspunsuri de suport, forumuri și analize de incidente, iar acele linkuri se acumulează la o adresă URL care vă aparține. O pagină actualizată săptămânal timp de doi ani e și un semnal credibil de prospețime pentru produsul căruia îi aparține.

Ce nu funcționează e tratarea intrărilor ca content marketing. O intrare umflată la trei paragrafe pentru lungime e mai proastă la treaba ei reală, adică să spună unui cititor într-o propoziție dacă ceva ce folosește s-a schimbat. Dacă vreți ca changelog-ul să susțină căutarea, puneți efortul în permalinkuri, în flux și în linkurile interne către el, și păstrați intrările scurte. Propria noastră pagină de exemple de changelog adună pagini care nimeresc acest echilibru bine.

Cum se abonează oamenii?

Dați-le căile pe care le folosesc deja: un flux RSS sau JSON pentru dezvoltatori, e-mail pentru cei care vor să audă doar lucrurile importante, și widget-ul din aplicație pentru toți cei care nu vor face niciodată vreunul din cele două. Întrebați ce vor să audă în loc să presupuneți, pentru că un cititor care vrea schimbări ce rup compatibilitatea și primește corecturi de text se dezabonează de la ambele.

Calea de adăugat ultima e cea care închide bucla. Când o intrare rezolvă ceva ce a cerut o anumită persoană, spuneți-i direct, în loc să sperați că citește pagina. La changeloop, intrarea se publică deodată pe pagină, flux și widget, iar persoana al cărei feedback din widget a devenit issue-ul GitHub închis de pull request e anunțată pe acel issue cu un link către intrare și vede intrarea în widget. Mecanismul e același ca orice abonament; diferența e că destinatarul deja a întrebat. Ăsta e argumentul dezvoltat în închiderea buclei de feedback din partea changelog-ului.

FAQ

Ar trebui pagina de changelog să fie pe un subdomeniu sau pe o cale? Implicit, o cale pe site-ul principal, pentru că moștenește autoritatea site-ului și nu are nevoie de infrastructură suplimentară. Un subdomeniu e justificat când un sistem diferit servește pagina.

Câte intrări ar trebui să arate pagina deodată? Suficiente cât să umple un ecran și nu mai mult, cu paginare după aceea. Încărcarea a doi ani de istorie într-un document e lentă și face intrarea cea mai nouă mai greu de găsit.

Ar trebui șterse vreodată intrările vechi? Nu. Sunt citate din afara site-ului vostru, iar linkurile se rup. Corectați o intrare la fața locului cu o notă, și păstrați adresa URL în viață.

Trebuie să apară fiecare schimbare pe pagină? Doar cele pe care un utilizator le-ar putea observa. O pagină care înregistrează refactorizări interne antrenează cititorii să treacă în viteză peste text, iar o pagină parcursă în viteză eșuează în ziua în care conține ceva urgent.

Afirmațiile tehnice din acest articol nu au fost verificate independent. Dacă ceva nu e corect, spune-ne și vom corecta.

Pe changeloop: Exemple de changelog, Documentație pentru dezvoltatori