Capitolato software: come scriverlo per un gestionale su misura

Un capitolato software è il documento che descrive cosa deve fare il programma che vuoi far costruire: chi lo userà, quali processi deve seguire, quali dati gestisce, con quali altri programmi deve parlare e come si capirà che il lavoro è finito. Si scrive in italiano corrente, senza linguaggio tecnico. Conta che sia concreto, con esempi veri presi dal tuo lavoro e priorità chiare fra ciò che è indispensabile e ciò che può aspettare.

Un buon capitolato fa risparmiare tempo a tutti. Permette di ricevere preventivi confrontabili, riduce i malintesi e diventa il riferimento del collaudo finale.

Perché scrivere un capitolato prima di chiedere un preventivo?

Perché senza un documento scritto ogni sviluppatore si fa un'idea diversa del programma. Uno pensa a uno strumento essenziale, un altro a un sistema completo, e i preventivi che ricevi non si possono confrontare.

Il capitolato serve anche a te. Scriverlo costringe a chiarire cose che si danno per scontate: chi approva un ordine, cosa succede quando un cliente paga in ritardo, quali eccezioni capitano nella pratica. Molte decisioni che altrimenti verrebbero prese a metà progetto, con costi e ritardi, si prendono prima.

Non deve essere perfetto. Una prima versione di poche pagine, scritta da chi conosce il lavoro, è già un ottimo punto di partenza. Il resto si completa insieme a chi svilupperà il programma.

Quali sezioni deve avere un capitolato?

Una struttura che uso spesso, adatta a un gestionale per una piccola o media impresa, è questa.

1. L'azienda e il problema: cosa fate, quante persone siete, cosa non funziona oggi.
2. Gli obiettivi: cosa deve cambiare dopo, possibilmente in modo misurabile.
3. Gli utenti: chi userà il programma, con quali ruoli e da quali dispositivi.
4. I processi: come si svolge oggi il lavoro e come dovrebbe svolgersi con il programma.
5. Le funzioni: l'elenco di ciò che il programma deve fare, diviso per priorità.
6. I dati: quali informazioni gestisce, quante sono e da dove arrivano quelle esistenti.
7. I collegamenti: con quali programmi deve scambiare dati.
8. I vincoli: norme, privacy, tempi, eventuali tecnologie già presenti in azienda.
9. Il collaudo: come si verificherà che il programma fa ciò che deve.
10. Gli aspetti contrattuali: proprietà, assistenza, manutenzione.

Come si descrivono i processi aziendali?

Raccontandoli come si racconterebbero a un collega appena assunto. Per ogni processo si scrive da dove parte, chi fa cosa, quali documenti si usano e dove finisce.

Per esempio: «Il cliente chiede un preventivo per telefono o dal sito. Il commerciale fa un sopralluogo, prende le misure e le scrive su un modulo di carta. In ufficio si prepara il preventivo su Excel partendo dal listino. Se il cliente accetta, si chiede un acconto e si ordina il materiale al fornitore.»

Questo paragrafo vale più di dieci righe come «il sistema dovrà gestire il flusso preventivi». Allegare i documenti veri, come il modulo del sopralluogo, il file Excel e un preventivo mandato, aiuta ancora di più.

Le eccezioni vanno scritte. «Se il cliente è un'impresa edile, il listino è diverso.» «Se il materiale non è disponibile, si propone un'alternativa.» Sono proprio le eccezioni a decidere se un programma verrà usato o abbandonato.

Come si dividono le funzioni per priorità?

In tre gruppi, scritti con onestà.

• Indispensabili: senza queste il programma non serve. Sono il cuore della prima versione.
• Importanti: servono, ma si può partire senza e aggiungerle dopo poche settimane.
• Desiderabili: sarebbero utili, si valutano quando il resto funziona.

Dividere le funzioni così permette di partire con una prima versione più piccola, metterla in mano alle persone e correggere la direzione presto. Permette anche di ricevere preventivi divisi per tappe, con costi chiari per ogni gruppo di funzioni. Ne parlo nella pagina sull'MVP, cioè la prima versione essenziale di un prodotto.

Cosa bisogna scrivere su dati e collegamenti?

Sui dati servono tre informazioni: quali sono, quanti sono e dove stanno oggi. «Circa duemila clienti in un file Excel, cinquemila articoli nel gestionale del magazzino, gli ordini degli ultimi cinque anni in un vecchio programma.» Questo dice a chi sviluppa quanto lavoro di importazione serve.

Sui collegamenti serve l'elenco dei programmi con cui il nuovo software deve parlare, con nome e versione: programma di fatturazione, negozio online, banca, centralino. Per ognuno va detto cosa deve passare e in quale direzione. Chi sviluppa verificherà poi la compatibilità, cioè se quei programmi hanno API utilizzabili.

Cosa non scrivere in un capitolato?

Ci sono errori comuni che rendono il documento meno utile.

• Imporre tecnologie senza motivo, come un linguaggio di programmazione o un database, a meno che non ci sia un vincolo reale.
• Copiare elenchi di funzioni dai siti dei software commerciali, che descrivono il loro prodotto e non il tuo lavoro.
• Usare frasi vaghe come «interfaccia semplice e intuitiva» senza esempi di cosa significa per te.
• Mettere tutto come indispensabile.
• Dimenticare chi userà il programma ogni giorno, e da quali dispositivi.

Meglio descrivere il problema e lasciare a chi sviluppa il compito di proporre come risolverlo. Se una proposta non ti convince, se ne parla.

Come si scrivono i criteri di collaudo?

Con casi concreti da provare. Un criterio di collaudo è una situazione con un risultato atteso: «Inserisco un preventivo per un cliente rivenditore con dieci articoli; il programma applica il listino rivenditori e il PDF riporta il totale corretto.»

Una ventina di casi così, scelti fra le situazioni più comuni e le eccezioni più delicate, bastano per un gestionale di media complessità. Il collaudo finale consiste nel provarli tutti, insieme. Se un caso non dà il risultato atteso, è chiaro cosa va sistemato.

Cosa va scritto su proprietà e assistenza?

Ci sono due cose che conviene chiarire prima di iniziare. La prima è a chi appartiene il codice scritto per te e se ti viene consegnato. Spiego le opzioni nella guida sulla proprietà del codice sorgente.

La seconda è cosa succede dopo la consegna: come si segnalano i problemi, in quanto tempo si interviene, come si chiedono e si quotano le modifiche, chi si occupa di server e backup. Scrivere queste aspettative nel capitolato permette di ritrovarle nella proposta.

Devo scriverlo da solo o con l'aiuto di qualcuno?

La prima bozza conviene scriverla tu, o chi conosce meglio il lavoro, perché nessuno conosce i tuoi processi meglio di chi li vive ogni giorno. Poi si può affinare con un aiuto tecnico, che trasforma i racconti in requisiti precisi e segnala le cose dimenticate.

È un lavoro che faccio spesso all'inizio dei progetti: dopo un paio di incontri, preparo un documento con processi, funzioni divise per priorità e casi di collaudo, che il cliente rilegge e corregge. Diventa la base della proposta e dei tempi, di cui parlo nella guida sui tempi di sviluppo di un software su misura. Se ti serve solo questo supporto, trovi come funziona nella pagina sulla consulenza tecnica.

Quanto deve essere lungo un capitolato?

Quanto serve a descrivere il lavoro, e non di più. Per un gestionale di una piccola impresa bastano spesso dieci o quindici pagine, più gli allegati con i documenti veri. Un capitolato di cento pagine non è migliore: spesso è pieno di elenchi generici che nessuno leggerà.

Conta che ogni funzione indispensabile sia descritta con un esempio, che le eccezioni importanti siano scritte e che i casi di collaudo siano chiari. Se dopo averlo letto chi sviluppa ha ancora domande, è normale: il capitolato apre la conversazione, e le risposte lo completano.

Ne parliamo?

Se stai pensando a un gestionale e non sai da dove partire per descriverlo, mandami anche solo una pagina scritta di getto con quello che non funziona oggi. Ti aiuto a trasformarla in un capitolato chiaro e in una proposta per tappe. Trovi come lavoro nella pagina sul gestionale su misura, nelle applicazioni web su misura e mi scrivi dalla pagina contatti.

Crediti delle immagini

• Copertina: foto di 2H Media su Unsplash