Nomi dei file: riconoscere documento, versione e stato
Di Redazione Quaderno dei Sistemi
Definisci una convenzione leggibile per i documenti di progetto ed evita sequenze di finale, definitivo e nuovissimo senza significato.
Un nome di file dovrebbe aiutare a riconoscere il contenuto senza doverlo aprire. Quando compaiono «finale», «finale2» e «finalissimo», il problema non è la fantasia del gruppo: manca una regola condivisa sullo stato del documento. Definisci prima la regola, poi rinomina con cautela.
Tre informazioni, non dieci
Una convenzione redazionale possibile è argomento, versione e stato: «guida-importazione_v03_revisione». È un esempio organizzativo, non uno standard obbligatorio. Se serve una data, chiarisci se indica creazione, revisione o pubblicazione. Non usare lo stesso campo per tutti e tre gli eventi.
Identificativi coerenti
Per i documenti che accompagnano un software, annota la versione a cui si riferiscono. Le release e i tag non sono sinonimi di «ultimo file nella cartella»: la documentazione GitHub distingue la release dal punto della cronologia identificato dal tag. Un manuale deve quindi dichiarare il proprio riferimento, non soltanto una data recente.
Gestire le eccezioni
Non rinominare automaticamente file collegati da altri documenti senza controllare i riferimenti. Prepara una piccola tabella con nome precedente e nuovo nome, prova i collegamenti e conserva il contesto. Se due file sembrano uguali, confrontali prima di cancellarne uno.
La convenzione funziona quando una persona diversa dall’autore riesce a scegliere il documento corretto. Fai una prova con tre file reali e una domanda concreta: «Quale devo usare per la versione installata?». Se la risposta resta ambigua, semplifica o aggiungi un indice.
Continua a leggere
- Schermate nei manuali: mostrare il passaggio senza nascondere il testo
- Consegna di un progetto: la checklist dei documenti