Come un team di documentazione ha corretto le pagine giuste chiedendo sulla pagina stessa

Un progetto open-source ha una buona documentazione e un vero problema: la guida di installazione è leggermente sbagliata. Un passaggio è cambiato due versioni fa, e ora i nuovi arrivati si bloccano nello stesso punto. Le persone se ne accorgono — ci sono lamentele sui social media e un paio di domande confuse nella chat della community — ma i manutentori non possono fare nulla al riguardo, perché nessuna delle lamentele dice **quale pagina**. "La vostra documentazione è obsoleta" è una sensazione, non una segnalazione di bug. Così il passaggio sbagliato rimane lì per mesi, allontanando silenziosamente ogni nuovo utente che cerca di iniziare. La documentazione vive o muore su questo ciclo: un lettore incontra un passaggio confuso o sbagliato, dice ai manutentori esattamente dove, e i manutentori lo correggono. Rompi l'"esattamente dove" e l'intero ciclo si ferma. ## Il problema: il feedback senza una posizione è rumore I lettori sono disposti ad aiutare. Saranno felici di dirti che una pagina è confusa. Quello che non faranno è l'archeologia necessaria per rendere quell'aiuto sfruttabile — copiare l'URL, trovare il canale di contatto giusto, descrivere il problema e annotare quale sezione e quale versione. Sono molti passaggi per qualcuno che sta cercando di imparare il tuo strumento, non di revisionare la tua documentazione. Quindi il feedback che arriva è privato dell'unica cosa che lo rende utile: la posizione. Un manutentore che legge "la documentazione dell'API è sbagliata" ha centinaia di pagine e nessuna idea di dove guardare. Una issue su GitHub aiuta, ma chiede a un lettore casuale di avere un account, comprendere il template della issue e cambiare completamente contesto uscendo dalla documentazione — un attrito che filtra la maggior parte dei feedback di passaggio, che è esattamente il feedback che coglie piccoli errori ad alto impatto. Il risultato è uno strano squilibrio: moltissimi lettori notano i problemi, quasi nessuno viene segnalato in una forma che puoi correggere. ## La soluzione: un link 'Segnala un problema' per pagina Metti un piccolo link **Segnala un problema con questa pagina** nel piè di pagina di ogni pagina della documentazione. È un link `mailto:` e il suo trucco è che precompila il percorso della pagina attuale nell'oggetto e nel corpo. Il lettore clicca, la sua email si apre con la posizione già catturata, e tutto ciò che deve aggiungere è cosa c'era di sbagliato. Poiché la documentazione di solito è costruita da un template o da un generatore di siti statici, puoi iniettare il percorso automaticamente. In un sito basato su template, inserisci la variabile della pagina direttamente nel link: ```html <a href="mailto:docs@yourproject.dev?subject=Docs issue: {{page.path}}&body=Page: {{page.path}}%0A%0AWhat is wrong or confusing:%0AWhat would make it clearer:"> Segnala un problema con questa pagina </a> ``` Oppure impostalo con una riga di script in modo che funzioni su qualsiasi pagina senza template: ```html <a id="docs-issue" href="#">Segnala un problema con questa pagina</a> <script> const a = document.getElementById('docs-issue'); const path = location.pathname; const body = 'Page: ' + path + '\n\nWhat is wrong or confusing:\nWhat would make it clearer:'; a.href = 'mailto:docs@yourproject.dev' + '?subject=' + encodeURIComponent('Docs issue: ' + path) + '&body=' + encodeURIComponent(body); </script> ``` Il generatore su questo sito produce il link codificato; lo script scambia solo il percorso in tempo reale. Ora ogni segnalazione nomina la pagina esatta nel suo oggetto, e un manutentore può saltare direttamente al file sorgente. ## Perché l'opzione sulla pagina supera un issue tracker per questo Un issue tracker è la casa giusta per una correzione, ma una pessima porta d'ingresso per il feedback. Richiede un account, un cambio di contesto e familiarità con il tuo processo — barriere che allontanano il lettore casuale che ha appena notato un errore di battitura in un esempio di codice. Il link `mailto:` incontra i lettori dove la confusione si verifica effettivamente: sulla pagina, in un clic, senza account. Cattura la lunga coda di piccole correzioni che non sopravvivrebbero mai al viaggio verso un tracker. I due funzionano bene insieme. Le segnalazioni arrivano via email, pre-etichettate con la pagina; un manutentore le seleziona e apre issue nel tracker solo per quelle che vale la pena tracciare. Ottieni il basso attrito dell'email all'ingresso e il rigore di un tracker sul retro. ## Configurazione 1. Scegli una casella di posta per la documentazione come `docs@` controllata dai manutentori. 2. Nel generatore, imposta il destinatario, un oggetto come "Docs issue: [percorso della pagina]" e un corpo che chiede cosa c'è di sbagliato e cosa potrebbe aiutare. 3. Aggiungi il link al piè di pagina del template della tua pagina, iniettando il percorso con la variabile di pagina del tuo generatore o il piccolo script sopra. 4. Indirizza la posta in arrivo tramite il tag dell'oggetto "Docs issue:" in modo che le segnalazioni arrivino in un unico posto. 5. Chiudi il cerchio: quando correggi una pagina segnalata, una risposta di una riga al lettore trasforma una segnalazione di bug in buona volontà. ## Cosa fa risparmiare Il primo risparmio è il **tempo dei manutentori speso a localizzare i problemi**. Quando ogni segnalazione nomina la pagina, salti il lavoro da detective e vai dritto alla correzione. Una segnalazione che un tempo era un inattuabile "qualcosa è sbagliato da qualche parte" diventa una modifica di due minuti. Il secondo è un **minor numero di utenti bloccati**. Gli errori di documentazione si accumulano: un passaggio di installazione sbagliato non fallisce una volta, fallisce per ogni nuovo arrivato finché qualcuno non lo corregge. Accorciare il tempo da "un lettore se ne accorge" a "un manutentore sa esattamente dove" significa che ogni passaggio errato allontana molte meno persone. Per uno strumento che cresce tramite l'adozione, sbloccare i nuovi arrivati è crescita. Il terzo è il **volume e l'onestà del feedback**. Poiché la segnalazione richiede un clic e nessun account, più lettori lo fanno — inclusi quelli che non aprirebbero mai una issue nel tracker. Vieni a conoscenza dei piccoli e imbarazzanti errori che erodono la fiducia, e ne vieni a conoscenza mentre hanno ancora importanza. ## Come renderlo ancora migliore - Precompila la **versione della documentazione o il commit** accanto al percorso, in modo da poter capire se una segnalazione è precedente a una recente riscrittura. - Aggiungi il link alle **pagine 404** nella tua documentazione, dove una pagina mancante è di per sé un segnale utile. - Mantieni l'indirizzo **offuscato** in modo che i bot non lo raccolgano da migliaia di pagine pubbliche. - Offri un'alternativa visibile per i lettori senza un'app di posta predefinita, come un indirizzo in testo semplice o un link al tracker. ## Punti chiave - Il feedback sulla documentazione senza una posizione è rumore; i lettori raramente fanno il lavoro di allegarne una. - Un link `mailto:` "Segnala un problema" per pagina precompila il percorso esatto, in modo che ogni segnalazione sia sfruttabile. - L'email sulla pagina cattura le correzioni casuali che un tracker filtra, per poi alimentare il tracker per le vere correzioni. - Fa risparmiare tempo ai manutentori, sblocca più velocemente i nuovi arrivati e fa emergere i piccoli errori che silenziosamente costano fiducia. Costruisci il tuo link di feedback per la documentazione nel [generatore](/#generator), o copia la configurazione qui sotto.