Un glossario piccolo per evitare istruzioni contraddittorie
Di Redazione Quaderno dei Sistemi
Scegli termini coerenti per azioni, oggetti e stati del software. Un metodo semplice per distinguere sinonimi utili e differenze reali.
Un glossario di progetto non deve cominciare con cento voci. Basta raccogliere i termini che generano dubbi durante il lavoro. Se «salvare», «pubblicare» e «inviare» producono effetti diversi, usarli come sinonimi rende le istruzioni rischiose anche quando ogni frase sembra grammaticalmente corretta.
Partire dai verbi dell’interfaccia
Elenca le azioni che cambiano uno stato. Per ciascuna scrivi che cosa succede, che cosa non succede e quale comando la esegue. In un esempio editoriale, salvare una bozza non significa renderla visibile al pubblico. La distinzione va mantenuta anche nei messaggi di conferma e nelle guide.
Collegare i termini ai documenti
Il README introduce il progetto, mentre il glossario può vivere in una pagina dedicata collegata da lì. Non sovraccaricare l’introduzione con tutte le definizioni. Se il gruppo usa una parola tecnica, aggiungi una spiegazione breve nel punto in cui compare per la prima volta.
Verificare un caso ambiguo
Scegli un’istruzione esistente e chiedi che cosa farebbe una persona seguendola alla lettera. Se due lettori immaginano risultati diversi, la definizione non è abbastanza precisa. Aggiungi un esempio concreto e correggi le pagine che usano la vecchia formulazione.
Conserva anche la ragione della scelta: «usiamo archivio per la raccolta, file per il singolo elemento». Il glossario diventa così una decisione condivisa e controllabile, non un elenco di parole complicate. Aggiornalo quando cambia il significato di una funzione, non soltanto quando cambia il suo nome.
Continua a leggere
- Consegna di un progetto: la checklist dei documenti
- Note di rilascio: cosa cambia per chi usa il programma