Organizzare un manuale software per attività
Di Redazione Quaderno dei Sistemi
Trasforma un indice di pulsanti in percorsi operativi: preparazione, azione e controllo del risultato. Un esempio per un archivio di documenti.
Un indice costruito soltanto sui nomi dei pulsanti costringe il lettore a tradurre il proprio obiettivo nell’interfaccia. Un manuale per attività parte invece da ciò che la persona vuole ottenere: importare un documento, ritrovarlo o esportarne una copia. Le funzioni restano descritte, ma dentro un percorso comprensibile.
Individuare il compito
Per un piccolo archivio, il primo capitolo potrebbe essere «aggiungere un documento e ritrovarlo». Elenca ciò che serve prima di iniziare, poi i passaggi e infine il controllo. Se il documento compare nella ricerca, hai un risultato osservabile; «operazione completata» senza spiegazione è meno utile.
Distinguere guida e riferimento
Le pagine di primo utilizzo accompagnano un caso. Le pagine di riferimento raccolgono campi, opzioni e limiti. Tenere separate queste funzioni evita di interrompere ogni istruzione con tutte le eccezioni possibili. Il README può fare da ingresso e rimandare alla documentazione estesa, come suggerisce l’organizzazione descritta da GitHub.
Provare la sequenza senza memoria
Rileggi i passi immaginando di non conoscere il programma. Ogni nome corrisponde a un elemento visibile? Un passaggio dipende da una scelta non ancora spiegata? L’esempio usa dati che il lettore possiede? Queste domande fanno emergere salti logici prima della pubblicazione.
Il modello riguarda documentazione d’uso del software. Non costituisce un manuale di sicurezza per macchine né una verifica di conformità: quei documenti hanno requisiti e responsabilità specifici che non vengono trattati qui.
Continua a leggere
- Nomi dei file: riconoscere documento, versione e stato
- Un glossario piccolo per evitare istruzioni contraddittorie