Quando viene scritta, la specifica funzionale spesso finisce su uno scaffale, o in una cartella di rete, dimenticata. Secondo Joel, quando la specifica funzionale non viene letta la colpa è di chi la scrive.

Cinque regole su come scrivere una specifica funzionale che merita attenzione e venga letta. (parte 2/2)

Quando viene scritta, la specifica funzionale spesso finisce su uno scaffale, o in una cartella di rete, dimenticata. Secondo Joel, quando la specifica funzionale non viene letta la colpa è di chi la scrive.

Nella prima parte di questo articolo abbiamo visto perchè scrivere la specifica funzionale è importante, vediamo qualche consiglio su come farlo.

Cinque regole per fare in modo che la specifica funzionale venga letta.

http://xkcd.com/243/

1. Scrivere in modo divertente.

Un modo per farlo? Joel suggerisce di essere specifici quando nessuno se lo aspetta, ad esempio tirando in ballo “Topolino” o “zia Caterina” invece del solito “l’utente”, dovrebbe rendere più piacevole la lettura. Se poi non sentite nelle vostre corde la chiave “umoristico/ironica”, come nel mio caso, cercate almeno di essere coinvolgenti.

2. Scrivere pensando di programmare cervelli umani.

Quello che scriviamo deve essere compreso da persone, non da computer: meglio non essere precisi come in un noioso manuale tecnico, se si il lettore ci guadagna in chiarezza. Normalmente è utile fornire all’inizio il quadro generale e scendere in seguito nei dettagli.

Per fare un buon lavoro, ogni frase deve poter essere compresa a pieno da parte del lettore nel contesto che stiamo costruendo: mettiamoci spesso nei panni di quel lettore

3. Scrivere semplice, il più semplice possibile.

Il linguaggio formale stanca presto il lettore, siate colloquiali. Quando avete difficoltà a scrivere una frase in modo chiaro, dividetela in due o tre frasi brevi. Evitate di scrivere intere pagine di solo testo: non vi sentiti anche voi smarriti quando ne incontrate una in un documento di questo tipo? Usate liste puntate, tabelle, immagini, grafici e tanto spazio bianco, in modo che la lettura risulti più “soffice”. Se volete approfondire il tema dello stile di scrittura, vi consiglio il manuale di stile di Wikipedia.

4. Revisionare e ri-leggere molte volte.

In questo modo potrete eliminare sia piccoli errori di ripetizioni, grammatica e sintassi, tanto fastidiosi quanto inutili per chi legge, sia più gravi mancanze legate all’aver scritto di getto, o aver modificato delle parti senza raccordare tutto il resto del documento.

5. Non usare template.

Evitate la tentazione di usare un template standard, uguale per tutte le vostre specifiche funzionali: non è una buona idea. Perchè? Per non annoiare il lettore con sezioni spesso non necessarie, che rendono voluminosi i documenti e che annullano l’interesse di chi legge tanto più sono inutili.

http://xkcd.com/1219/

Quando scrivere la specifica funzionale.

La specifica funzionale vive col progetto, e si smette di aggiornarla solo quando non c’è più bisogno di sviluppare codice.

Chi deve scrivere la specifica funzionale, e chi no.

La figura responsabile della specifica funzionale deve essere di tipo tecnico, ma non necessariamente un buon programmatore. Deve essere capace di relazionarsi col cliente, di progettare interfacce grafiche e di scrivere in modo chiaro. NB: essere carismatici aiuta, secondo Joel :)

Non solo sviluppatori.

Non promuovere uno sviluppatore al ruolo di chi scrive la specifica funzionale. Spesso gli mancano una o più delle doti richieste: scrivere chiaramente in italiano, un po’ di diplomazia, consapevolezza del mercato, buone capacità di UI design, empatia verso il prossimo. Allo stesso modo, non far scrivere la documentazione funzionale a un responsabile marketing, altrimenti peggio per voi!

Per scoprire a cosa cerchiamo di applicare queste regole, dai uno sguardo ai nostri case study.

Grazie a xkcd per le immagini: Appropriate TermReports.

Share this on

Share |

On same topics

Commenti

comments powered by Disqus