Come costruire una pagina di changelog che si segue

Una pagina di changelog vale la pena costruirla quando qualcuno ci tornerebbe. È un’asticella più alta che averne semplicemente una, ed è l’asticella su cui la maggior parte fallisce: una pagina che esiste, è collegata nel footer, si aggiorna a raffiche e non la visita nessuno tranne durante un incidente. Le decisioni che separano le due si prendono prima di scrivere qualsiasi cosa, e riguardano soprattutto dove vive la pagina e cos’altro viene generato dallo stesso contenuto.

Cos’è una pagina di changelog?

È l’elenco pubblico e datato di cosa è cambiato in un prodotto, su una URL che vi appartiene. È una di cinque superfici su cui possono apparire le stesse voci, e la domanda utile non è quale scegliere ma quale sia canonica e quali vengano generate a partire da essa.

Scegliete una fonte canonica, pubblicate una volta, e generate il resto. I team che mantengono pagina e widget separatamente a mano finiscono con due testi che non concordano, e la discrepanza la scopre un cliente.

Dove dovrebbe vivere una pagina di changelog?

Sul vostro dominio, su un percorso stabile, con ogni voce indirizzabile singolarmente. Le tre collocazioni comuni sono un percorso sul sito principale, un sottodominio, e una sezione della documentazione. Un percorso sul sito principale è la scelta predefinita contro cui argomentare, non a favore: eredita l’autorità del sito, non serve un certificato o DNS extra, e mantiene la pagina nella stessa navigazione di tutto il resto.

Un sottodominio è la risposta giusta quando la pagina è servita da un sistema diverso dal sito di marketing e altrimenti fareste proxy. Il costo è che accumula autorità separatamente. Mettere il changelog nei docs è giusto quando il pubblico è formato da sviluppatori, per la ragione trattata in changelog di API: chi legge di solito è già lì.

Più della scelta conta che le voci siano collegabili singolarmente. Le persone collegano le voci nelle revisioni degli incidenti e nei ticket interni, e una voce che si può collegare solo come “il changelog, scorri giù” finisce incollata come screenshot al suo posto.

Cosa serve a una pagina di changelog?

Cinque cose, e sulle prime due falliscono la maggior parte delle pagine. Una voce datata per cambiamento, la più recente per prima. Una categoria o etichetta per voce, per poter scorrere in cerca del tipo che interessa. Un permalink per voce. Una via di iscrizione. Una ricerca o filtro oltre le circa cinquanta voci.

Tutto il resto è opzionale. Gli screenshot aiutano e costano manutenzione. I nomi degli autori costruiscono fiducia in alcuni prodotti e rumore in altri. I numeri di versione contano per i chiamanti di un’API e per quasi nessun altro. Keep a Changelog è una scelta predefinita ragionevole per le etichette se non avete motivo di inventarne di vostre, e la sua regola centrale è quella da tenere anche se scartate il resto: il log è per gli esseri umani.

Raggruppate per data invece che per release quando il vostro prodotto rilascia continuamente. Un lettore che scandaglia “questo era prima o dopo il nostro incidente del nove” cerca una data, e una pagina organizzata per numero di versione lo costringe a fare i conti.

Pagina o widget in-app?

Entrambi, da un’unica fonte. La pagina è dove vivono ricerca, link e il registro lungo. Il widget è come raggiungete la maggioranza degli utenti che non visiterà mai la pagina, e funziona perché appare nel prodotto che stanno già usando.

Il fallimento del widget è l’interruzione. Un badge che chiede attenzione per ogni voce viene scartato in modo permanente entro una settimana, il che vi costa il canale per la voce che contava davvero. Contate i non letti dall’ultima volta che il lettore ha guardato, seminate il contatore in silenzio alla prima visita così nessuno viene accolto da un badge di un anno di storia, e lasciate che sia il lettore ad aprirlo invece di aprirlo per lui.

Come si rende leggibile dalla macchina una pagina di changelog?

Pubblicate le stesse voci come feed. Un feed JSON è l’opzione a minore attrito per chiunque lo consumi via codice, e un feed RSS è ciò che si aspetta uno sviluppatore che si iscrive in un reader. Entrambi costano poco una volta che le voci sono dati strutturati invece di HTML scritto a mano, il che è l’argomento reale per mantenere strutturata la copia canonica.

Marcate anche la pagina. Le voci sono opere con data e titolo, e schema.org fornisce il vocabolario. Vale la pena per lo stesso motivo dei permalink: rende la pagina utilizzabile da cose che non sono un browser, incluso il processo di release di un cliente. Niente di tutto questo funziona se le voci sottostanti non sono mai state dati strutturati fin dall’inizio; formati file del changelog copre cosa costa ciascuno tra Markdown, JSON e YAML come fonte di verità da cui questo feed e questo markup vengono davvero generati.

Una pagina di changelog aiuta la SEO?

Indirettamente e lentamente. Le voci singole raramente posizionano, perché non puntano a nessuna query che qualcuno digita. La pagina si guadagna il suo posto tramite i link: le voci vengono citate in risposte di supporto, forum e analisi degli incidenti, e quei link si accumulano su una URL che vi appartiene. Una pagina aggiornata ogni settimana per due anni è anche un segnale di freschezza credibile per il prodotto a cui appartiene.

Ciò che non funziona è trattare le voci come content marketing. Una voce gonfiata a tre paragrafi per allungarla è peggiore nel suo lavoro reale, cioè dire a un lettore in una frase se qualcosa che usa è cambiato. Se volete che il changelog sostenga la ricerca, mettete lo sforzo nei permalink, nel feed e nei link interni verso di esso, e lasciate le voci brevi. La nostra pagina di esempi di changelog raccoglie pagine che colgono questo equilibrio.

Come si iscrive la gente?

Dategli le vie che già usano: un feed RSS o JSON per gli sviluppatori, email per chi vuole sentire solo le cose importanti, e il widget in-app per tutti quelli che non faranno mai né l’uno né l’altro. Chiedete cosa vogliono sentire invece di darlo per scontato, perché un lettore che vuole breaking change e riceve correzioni di testo si disiscrive da entrambi.

La via da aggiungere per ultima è quella che chiude il ciclo. Quando una voce risolve qualcosa che una persona specifica ha chiesto, ditelo direttamente invece di sperare che legga la pagina. In changeloop la voce viene pubblicata in una sola volta su pagina, feed e widget, e una persona il cui feedback dal widget è diventato l’issue GitHub chiusa dalla pull request viene avvisata su quell’issue con un link alla voce, e vede la voce nel widget. Il meccanismo è lo stesso di qualsiasi iscrizione; la differenza è che chi riceve ha già chiesto. È l’argomento sviluppato in chiudere il ciclo di feedback dal changelog.

FAQ

La pagina di changelog dovrebbe stare su un sottodominio o un percorso? Un percorso sul sito principale per default, perché eredita l’autorità del sito e non serve infrastruttura extra. Un sottodominio si giustifica quando un sistema diverso serve la pagina.

Quante voci dovrebbe mostrare la pagina alla volta? Abbastanza da riempire uno schermo e non di più, con paginazione dopo. Caricare due anni di storia in un documento è lento e rende più difficile trovare la voce più recente.

Le voci vecchie andrebbero mai cancellate? No. Vengono citate da fuori del vostro sito e i link si rompono. Correggete una voce sul posto con una nota, e mantenete viva la URL.

Ogni cambiamento deve apparire sulla pagina? Solo quelli che un utente potrebbe notare. Una pagina che registra refactoring interni allena i lettori a scorrere senza leggere, e una pagina scorsa senza leggere fallisce il giorno in cui porta qualcosa di urgente.

Le affermazioni tecniche di questo articolo non sono state verificate in modo indipendente. Se qualcosa non è corretto, faccelo sapere e lo correggeremo.

Correlati su changeloop: Esempi di changelog, Documentazione per sviluppatori