La maggior parte dei ticket di supporto per i prodotti di codice sorgente non riguarda bug. Si tratta di problemi di installazione, domande sulla configurazione e richieste del tipo “come cambio X” a cui avrebbero risposto poche pagine ben posizionate. Una buona documentazione software per i clienti è organizzata intorno a queste domande: cosa serve all’acquirente per installare l’app, configurarla, usarla, personalizzarla, aggiornarla e sistemarla quando qualcosa va storto.
La documentazione influisce anche sulla decisione di acquistare. È uno dei segnali di fiducia descritti nella nostra guida su come vendere il codice sorgente della tua web app o SaaS, e i revisori di AppTrovo verificano che ci siano istruzioni chiare di installazione e utilizzo prima che un prodotto venga pubblicato. Questa guida ti mostra cosa scrivere, in quale ordine e come mantenerlo accurato quasi senza sforzo aggiuntivo.
L’obiettivo non è avere più pagine. È avere meno ticket per vendita, ed è questo che rende redditizia nel tempo una licenza una tantum.
Di quali documenti ha bisogno un prodotto di codice?
Chi acquista codice sorgente arriva con obiettivi diversi in momenti diversi. Separa la documentazione per obiettivo, così ogni lettore trova rapidamente la sua risposta. Il framework Diátaxis è un modello noto per questa suddivisione tra tutorial, guide pratiche, riferimento e spiegazione. Per una web app da vendere, sei documenti coprono quasi tutto:
| Documento | Domanda del lettore | Previene ticket come |
|---|---|---|
| README / Avvio rapido | Cos’è e come lo faccio funzionare? | “Da dove comincio?”, “Quale file devo caricare?” |
| Guida all’installazione | Come lo installo sul mio server, passo dopo passo? | “Pagina bianca dopo il caricamento”, “Errore di connessione al database” |
| Riferimento di configurazione | Cosa fa ogni impostazione e variabile d’ambiente? | “Le email non vengono inviate”, “Come cambio la valuta?” |
| Guida utente | Come svolgo un’attività nell’app? | “Come aggiungo un membro dello staff?”, “Dove sono i report?” |
| Guida alla personalizzazione | Come modifico il codice in sicurezza? | “Come cambio il logo?”, “Come aggiungo un campo?” |
| Risoluzione dei problemi e note di aggiornamento | Qualcosa si è rotto, oppure voglio la nuova versione | “Errore 500 dopo l’aggiornamento”, “I job in coda non vengono eseguiti” |
Includi la documentazione nel download (una cartella docs/ o un file HTML) e pubblica lo stesso contenuto online. Gli acquirenti che cercano un messaggio di errore troveranno una pagina pubblica; quelli su un server senza accesso a internet potranno comunque leggere la copia locale.
Inizia con un README scritto per gli acquirenti
Il README del tuo repository probabilmente l’hai scritto per te stesso. Il README per un acquirente risponde a domande diverse già nella prima schermata:
- Cos’è, in una frase.
- Requisiti: versione del linguaggio, estensioni, database, cron, coda, eventuali servizi di terze parti a pagamento.
- Cosa c’è nello ZIP: quale cartella caricare, quale contiene la documentazione, quale è facoltativa (file di design, dati di esempio).
- Il percorso più rapido per avere l’app funzionante: da cinque a dieci righe, con un link alla guida all’installazione completa.
- Credenziali predefinite create dall’installer, con un promemoria per cambiarle.
- Dove trovare aiuto: link alla documentazione, come aprire un ticket di supporto e cosa includervi.
- Versione e link al changelog.
Modello di guida all’installazione
La guida all’installazione previene più ticket di tutto il resto messo insieme. Scrivila installando il tuo prodotto su un server pulito mentre prendi appunti, mai a memoria. Usa questa struttura:
- Prima di iniziare. Una checklist che l’acquirente può spuntare: accesso al server, versione di PHP o del runtime, estensioni richieste, un database e un utente con privilegi completi su di esso, un dominio che punta al server, certificato SSL, possibilità di configurare un cron job.
- Carica i file. Indica esattamente quale cartella va dove e quale cartella deve essere la web root (per un’app Laravel,
public/). Aggiungi una nota per l’hosting condiviso nel caso in cui la web root non possa essere modificata. - Installa le dipendenze se non sono incluse, con i comandi esatti, come
composer install --no-dev --optimize-autoloader. - Crea il file di ambiente. Copia
.env.examplein.enved elenca i valori da modificare. - Imposta i permessi dei file. Indica le directory che devono essere scrivibili, ad esempio
storage/ebootstrap/cache/, e spiega il perché invece di consigliare 777. - Esegui l’installer o le migrazioni. Mostra cosa chiede ogni schermata dell’installer, compreso il passaggio della chiave di licenza.
- Configura le attività pianificate e le code. Fornisci la riga cron esatta e spiega come eseguire o supervisionare i worker delle code.
- Primo accesso e prime attività. Credenziali predefinite, le prime tre impostazioni da cambiare e come inviare un’email di prova.
- Verifica l’installazione. Un breve elenco di cose che ora dovrebbero funzionare, come “la dashboard si carica”, “arriva un’email di prova”, “l’attività pianificata compare nel log”.
- Se qualcosa è andato storto: link ai cinque errori di installazione più comuni nella tua pagina di risoluzione dei problemi.
Aggiungi una breve sezione separata per ogni configurazione di hosting comune che supporti: un VPS con Nginx, un VPS con Apache, hosting condiviso con cPanel, Docker. Se non ne supporti una, dillo. Gli acquirenti possono anche imparare il procedimento generale da guide come come installare una web app Laravel su un VPS, ma la tua guida deve comunque coprire i passaggi specifici del tuo prodotto.
Scrivi un riferimento di configurazione, non solo commenti nel .env
I commenti in .env.example aiutano gli sviluppatori, ma molti acquirenti sono imprenditori o sviluppatori junior. Una tabella di riferimento risponde in un unico posto alla domanda “cosa fa questo e quando devo cambiarlo?”.
| Variabile | Predefinito | Cosa fa | Quando cambiarla |
|---|---|---|---|
APP_URL | http://localhost | URL di base usato nei link e nelle email | Sempre; impostala sul tuo dominio reale con https |
MAIL_MAILER | log | Come vengono inviate le email | Impostala su smtp o sul tuo provider prima di andare in produzione |
QUEUE_CONNECTION | sync | Se i job in background vengono eseguiti subito o in un worker | Usa database o redis sui siti molto trafficati ed esegui un worker |
APP_TIMEZONE | UTC | Fuso orario per date e attività pianificate | Impostala sul fuso orario della tua attività |
La tabella qui sopra è un esempio; documenta ogni variabile letta dal tuo prodotto. Fai lo stesso per le schermate delle impostazioni all’interno dell’app: cosa cambia ogni impostazione e qual è il valore predefinito sicuro.
Risoluzione dei problemi: scrivi le voci intorno ai messaggi di errore reali
Gli acquirenti cercano il testo esatto che vedono. Una pagina di risoluzione dei problemi che usa quelle stringhe esatte come titoli viene trovata dai motori di ricerca e dalla ricerca interna del sito dell’acquirente. Usa questo formato per ogni voce:
Errore:
SQLSTATE[HY000] [2002] Connection refusedCosa significa: l’app non riesce a raggiungere il server del database.
Cause comuni:
DB_HOSToDB_PORTerrati; il servizio del database non è in esecuzione; l’host accetta solo connessioni da localhost.Come risolvere: controlla i valori in
.env, verifica che il database sia in esecuzione, prova127.0.0.1invece dilocalhost, quindi svuota la cache della configurazione.
Inizia dagli errori che già conosci: la pagina bianca con il debug disattivato, l’errore 500 dopo il caricamento, gli errori di permessi sulla cartella storage, l’estensione PHP mancante, i fallimenti di autenticazione della posta, il cron che non viene eseguito e i fallimenti della verifica della licenza. Poi aggiungi una nuova voce ogni volta che un ticket ne rivela una nuova.
Guida alla personalizzazione: rispondi a “come cambio X”
Le richieste di personalizzazione sono la seconda fonte di ticket per numero, e molti venditori continuano a rispondere una per una all’infinito. Documenta una volta per tutte le dieci modifiche più comuni:
- Cambiare logo, colori e nome dell’app.
- Modificare i modelli delle email e i testi delle notifiche.
- Aggiungere o modificare una lingua o una stringa di traduzione.
- Aggiungere un campo a un modulo e al database.
- Aggiungere una voce di menu o una pagina.
- Cambiare valuta, formato della data e formato dei numeri.
- Collegare un diverso provider di pagamento, SMS o email.
- Aggiungere un ruolo o un permesso.
Per ciascuna, mostra dove si trova il file, cosa cambiare e come mantenere la modifica con gli aggiornamenti futuri. Quest’ultimo punto è importante: se gli acquirenti modificano i file del core, ogni aggiornamento diventa un ticket di supporto. Indirizzali invece verso punti di estensione, cartelle di override o configurazione. La nostra guida su supporto, aggiornamenti e versionamento spiega come progettare le release in modo che le installazioni personalizzate possano essere aggiornate.
Trasforma i ticket in documentazione ogni mese
La documentazione diventa obsoleta e non copre mai tutto al primo tentativo. Un semplice ciclo mensile la mantiene utile:
- Assegna un’etichetta a ogni ticket con una categoria: installazione, configurazione, utilizzo, personalizzazione, bug, pre-vendita, altro.
- Una volta al mese, conta le etichette. Scegli le tre domande più frequenti che non sono bug.
- Scrivi o migliora la pagina che avrebbe risposto a ciascuna, usando nel titolo le parole stesse dell’acquirente.
- Rispondi ai ticket futuri con un link e un riepilogo di una riga. Se il link non risolve il problema, la pagina va migliorata.
- Correggi il prodotto quando la stessa confusione continua a ripresentarsi. Un messaggio di errore più chiaro o un controllo nell’installer è meglio di qualsiasi documento.
Come esempio illustrativo, un venditore che riceve 40 ticket al mese e scopre che 15 riguardano la configurazione delle email può di solito eliminarne la maggior parte con una buona pagina e un passaggio dell’installer che invia un’email di prova.
Fai in modo che il prodotto si documenti da solo
La migliore documentazione è quella che l’acquirente non ha mai bisogno di aprire:
- Controlli nell’installer che verificano versione di PHP, estensioni, cartelle scrivibili e connessione al database, e spiegano gli errori in un linguaggio semplice.
- Messaggi di errore utili che dicono cosa fare dopo (“Il server di posta ha rifiutato l’accesso. Controlla MAIL_USERNAME e MAIL_PASSWORD nelle Impostazioni”).
- Una pagina di stato del sistema nell’area di amministrazione che mostra versioni, stato delle code, ultima esecuzione del cron e permessi dello storage. Gli acquirenti possono farne uno screenshot quando aprono un ticket.
- Testi di aiuto in linea accanto alle impostazioni facili da fraintendere.
- Stati vuoti che spiegano l’azione successiva (“Ancora nessun membro dello staff. Aggiungi il primo”).
Regole di stile che rendono la documentazione più facile da seguire
- Scrivi passaggi numerati per tutto ciò che si fa in sequenza, un’azione per passaggio.
- Mostra comandi e percorsi esatti, e indica dove eseguirli.
- Indica il risultato atteso dopo i passaggi importanti, così i lettori capiscono quando qualcosa è andato storto.
- Usa screenshot per le schermate delle impostazioni e aggiornali quando l’interfaccia cambia.
- Scrivi in un inglese americano semplice con frasi brevi; molti acquirenti leggono tramite uno strumento di traduzione.
- Versiona la documentazione. Segnala le sezioni che valgono solo per determinate versioni e conserva le note di aggiornamento per ogni release.
I principi di documentazione di Write the Docs, gratuiti, sono una buona checklist per chiarezza e struttura.
Checklist della documentazione prima dell’invio
- Il README spiega cos’è, i requisiti, cosa c’è nello ZIP, l’avvio rapido, le credenziali predefinite e dove trovare aiuto.
- Guida all’installazione testata su un server pulito, con una sezione per ogni configurazione di hosting supportata.
- Il riferimento di configurazione copre ogni variabile d’ambiente e ogni impostazione importante.
- La guida utente copre le attività principali per ogni ruolo.
- La guida alla personalizzazione copre le dieci modifiche più comuni e come mantenerle con gli aggiornamenti.
- La pagina di risoluzione dei problemi usa come titoli i messaggi di errore esatti.
- Changelog e note di aggiornamento sono inclusi.
- La documentazione è sia nel download sia online.
Prima di inviare, confronta il tutto con la checklist per l’invio dei prodotti e con gli standard del codice di AppTrovo. Quando la documentazione è pronta, la tua scheda prodotto può collegarvisi dalla sezione dei requisiti, il che aiuta anche gli acquirenti in fase di pre-vendita.
Domande frequenti
Cosa dovrebbe includere la documentazione software destinata ai clienti?
Come minimo: un README, una guida all’installazione, un riferimento di configurazione, una guida utente, una guida alla personalizzazione e una pagina di risoluzione dei problemi con le note di aggiornamento. Ogni documento risponde a una domanda diversa, quindi tienili separati e collegali tra loro.
La documentazione deve stare nello ZIP o online?
In entrambi. La copia nello ZIP corrisponde sempre alla versione in possesso dell’acquirente. La copia online è ricercabile, facile da linkare nelle risposte del supporto e può essere aggiornata tra una release e l’altra. Chiarisci a quale versione si riferisce ogni pagina online.
Quanto deve essere dettagliata una guida all’installazione?
Abbastanza dettagliata da permettere a chi ha già installato una web app, ma mai la tua, di completare l’installazione senza contattarti. Includi comandi esatti, percorsi, permessi richiesti e il risultato atteso dopo ogni passaggio importante. Testala su un server pulito per ogni release che cambia i requisiti.
Come capisco quale documentazione scrivere per prima?
Guarda i tuoi ticket di supporto e le domande pre-vendita. Di solito installazione e configurazione vengono prima, seguite dalle richieste di personalizzazione più comuni. Se non hai ancora ticket, installa tu stesso il prodotto su un server pulito e documenta ogni punto in cui hai dovuto fermarti a riflettere.
Una buona documentazione riduce davvero i rimborsi?
Le installazioni fallite e le aspettative deluse sono motivi comuni per cui gli acquirenti chiedono un rimborso, e requisiti chiari insieme a una guida all’installazione testata affrontano entrambi. I rimborsi su AppTrovo seguono la politica di rimborso, ma prevenire il problema costa sempre meno che gestire la richiesta.