Perché scrivere documenti di progettazione software è importante

Congratulazioni, sei uno sviluppatore indipendente competente. Dai tuoi umili inizi, magari lavorando come tester, sei passato a sviluppatore di un team, poi sviluppatore senior, e ora hai fatto un altro salto, il più grande di tutti, a lavorare direttamente con i clienti.

Ma dove le altre transizioni erano lineari, quest'ultima era esponenziale. Mentre in passato ricevevi i tuoi ordini di marcia da un datore di lavoro che lavorava con i clienti o era lui stesso nel settore del software, ora tutte quelle responsabilità che una volta erano distribuite tra test di esperti, gestione del programma, ecc., sono tutte tue. E ora stai lavorando con clienti che non sono nel business del software; sono in un'altra azienda che ha bisogno di un software e non hanno una visione chiara e precisa di ciò che vogliono da te. Questa è una sfida molto più grande di quanto sembri.

*Nota:* Qui sto descrivendo i clienti più piccoli che vogliono un esercito di un solo uomo dal loro sviluppatore. Non è l'unica strada che un freelance può prendere, e quelli non sono gli unici clienti con cui lavoriamo in Toptal, ma è la strada che mi piace di più. Naturalmente, se lavori in un team e non da solo, alcuni dei seguenti non si applicano. Ad esempio, se stai utilizzando metodologie Agile o Scrum, probabilmente vorrai strutturare le tue pietre miliari in modo leggermente diverso.

Avete tutti sentito parlare dell'importanza suprema della comunicazione. Non puoi lavorare ricevendo alcune frasi concise su Skype e dicendo "Ci vediamo tra tre mesi quando avrò finito". Devi essere in comunicazione con il tuo cliente e in ogni fase del tuo lavoro accertarti di avere idee congruenti sull'obiettivo, perché è davvero raro che un cliente ti invii wireframe e una specifica funzionale dettagliata. Avrai un'idea molto generale di ciò che il software dovrebbe fare, aspetto e flusso. Se scrivi un'applicazione in base alla descrizione superficiale con cui di solito inizi, non c'è quasi nessuna possibilità che il tuo cliente sia soddisfatto del risultato. In ogni fase, è necessario eseguire un'iterazione per avvicinarsi all'accordo.

Avendo lavorato per anni in aziende che erano esse stesse nel settore del software, dove tutti i membri del team provenivano dalla stessa cultura, parlavano la stessa lingua madre, lavoravano nello stesso corridoio, si incontravano quotidianamente, ecc., è stato interessante notare che il l'azienda non ha ancora ottenuto ciò che voleva la metà delle volte. Non commettere errori: la sfida qui è enorme.

Perché i documenti di progettazione software sono importanti

Pertanto, quando si intraprende un nuovo progetto, prima ancora di aprire Xcode o Visual Studio, è necessario disporre di obiettivi di progettazione chiari e concordati . E questi obiettivi dovrebbero essere stabiliti in un documento di specifica. Se il client non ne ha scritto uno, dovresti scriverlo e inviarlo a loro per la revisione prima ancora di aprire il tuo IDE. E se incontri un cliente che dice: "Non abbiamo tempo per i documenti di progettazione", candidamente, dovresti abbandonare il progetto perché hai problemi in anticipo. La specifica non deve essere particolarmente lunga; possono essere solo poche pagine, ma almeno dovrebbe disporre l'interfaccia utente, includere wireframe (se è presente un componente dell'interfaccia utente) e impostare tappe di completamento.

Senza questo documento, finirai in un circolo vizioso di aspro equivoco, i clienti contestano ciò che ti hanno detto o ciò che hai detto loro, inviando con rabbia taglia e incolla di comunicazioni precedenti, interpretando e discutendo fino al momento in cui il cliente richiede che apporti modifiche per rendere l'applicazione conforme a "ciò che hanno effettivamente chiesto" e si aspetta che tu apporti tali modifiche gratuitamente.

Con questo documento di progettazione del software, avrai una risposta a tali cavilli: quando sorgono disaccordi, puoi fare riferimento alla specifica che il cliente ha accettato e firmato, sottolineando che l'hai soddisfatta alla lettera. Invece di argomentazioni arrabbiate, apporterai emendamenti e chiarimenti al documento. Semmai, il cliente si scuserà per aver lasciato sfuggire l'imprecisione in primo luogo.

Tutti noi vogliamo clienti soddisfatti. Tutti noi vogliamo un rapporto di lavoro amichevole. E tutti noi vogliamo l'orgoglio di un lavoro ben fatto. Ma questi non possono essere raggiunti se c'è qualche vaghezza su quale sia effettivamente il lavoro. Se il tuo cliente dice che un documento di progettazione è troppo lavoro extra, è tuo compito spiegargli che il vero lavoro extra emergerà quando sarà necessario apportare delle revisioni a causa di una sorta di malinteso. Se il cliente insiste ancora sul fatto che tu avanzi senza un tale documento, dovresti accettare il fatto che hai una relazione impraticabile e andartene.

Cosa dovrebbe effettivamente specificare la specifica di progettazione del software?

Come minimo, dovrebbe essere una descrizione dell'applicazione desiderata, dei criteri per il completamento e delle tappe fondamentali. Ricorda che stai condividendo ciò che è meglio descritto come un documento dei requisiti e delle funzioni, non una specifica di implementazione. E a meno che un'implementazione specifica non sia un obiettivo dichiarato del cliente, come farlo funzionare dipende da te.

Interfaccia utente

La maggior parte dei progetti sono applicazioni, non librerie o framework. Ma se ti capita di avere uno di questi come risultato finale, ritieniti fortunato perché l'interfaccia utente è di gran lunga il componente più problematico del tuo modello di documento di progettazione e porta quasi sempre a malintesi. Molti clienti ti invieranno illustrazioni perfette create in un editor grafico da un grafico che non è un programmatore. Ma il problema è: queste illustrazioni non dicono nulla sulle animazioni, sugli stati di controllo (ad es. Questo pulsante è disabilitato? Scompare quando è inutilizzabile?), o anche sulle azioni da eseguire quando viene premuto un pulsante.

Prima di iniziare a scrivere il codice dietro queste illustrazioni, dovresti essere in grado di rispondere a tutte queste domande. Nello specifico dovresti sapere:

1. I controlli sono sempre visibili e/o abilitati? In quali condizioni cambiano i loro stati?
2. Sembra una bitmap: è un pulsante?
3. Quali transizioni si verificano tra questi stati e punti di vista? E come dovrebbero essere animati?

Se spetta a te generare l'interfaccia utente per la concorrenza del client, fai lo stesso al contrario: utilizza uno strumento wireframe e crea un set completo di layout dello schermo, comprese eventuali varianti che le viste mostrano in diversi stati dell'applicazione. Questo può essere un lavoro esauriente e noioso, ma non te ne pentirai: può salvarti dalla riscrittura di enormi quantità di codice e dalla ricreazione di interfacce a causa di un piccolo malinteso con importanti implicazioni. Se stai creando un'applicazione doppia (ad esempio, sia per iPhone che per iPad), crea wireframe separati per entrambi.

Anche le dimensioni dello schermo sono importanti. Ci sono (al momento della scrittura) tre dimensioni di schermi di iPhone. Wireframe separati per schermi da 3,5" e 4" sono probabilmente eccessivi, ma potrebbe essere necessario realizzarli; nella maggior parte dei casi, puoi semplicemente cambiare le proporzioni.

Se il tuo cliente ti fornisce la grafica, assicurati che siano dimensionate correttamente con le proporzioni corrette; il morphing di qualsiasi bitmap con testo o oggetti (come i cerchi) introdurrà distorsioni. Se non corrispondono, chiedi al cliente di ricrearli con dimensioni corrispondenti. Non dare per scontato di poter allungare una schermata iniziale da 3,5 pollici in una schermata iniziale da 4 pollici e semplicemente rotolare con essa.

Funzionalità

Domande chiave da porre nel documento di progettazione dell'applicazione:

• Che cosa fa l'applicazione e quanto velocemente lo fa?
• Quali sono le possibili condizioni di guasto e come vengono gestite?
• Quali operazioni una tantum vengono eseguite alla prima esecuzione (ovvero dopo l'installazione)?
• Se l'utente crea voci di qualsiasi tipo (es. segnalibri), quali sono le limitazioni?

Generalizza queste idee e sii il più dettagliato e completo possibile, perché errori o incomprensioni qui significheranno riscrivere il codice.

Pietre miliari

Il tuo modello di specifica dovrebbe impaginare le pietre miliari chiare. Se il tuo cliente scrive il design funzionale e dell'interfaccia utente, dovresti successivamente concordare una serie di pietre miliari. A volte si tratta anche di soglie di fatturazione, ma almeno forniscono una metrica chiara verso il completamento. Le pietre miliari possono essere in termini di funzionalità e/o componenti; possono anche essere applicazioni separate se il concerto coinvolge una suite di risultati finali. Quando possibile, le pietre miliari dovrebbero avere una durata approssimativamente uguale.

Esempio di specifica di progettazione del software

Qui, illustrerò la struttura di esempio di un documento di progettazione corretto. Naturalmente, questo modello dovrebbe essere modificato in base alle esigenze. Per un altro esempio, vedere la specifica di esempio di Joel Spolsky, basata su questo articolo. Si avvicina al documento in modo leggermente diverso, ma condivide un sentimento simile.

Dichiarazione degli obiettivi

Includere un breve paragrafo che descriva il progetto e il pubblico a cui è destinato.

descrizione funzionale

Cosa fa l'applicazione ? Quali stati dell'applicazione (descrizioni di alto livello degli scenari utente principali) incontreranno l'utente?

Ad esempio, la tua descrizione funzionale potrebbe essere simile a:

• Prima corsa
• Creazione di un nuovo _____ (gioco, ricerca, ecc.)
• Operazioni
• Comportamento in background e in primo piano

Interfaccia utente

Includi wireframe per ogni pagina, con descrizioni dettagliate di:

• Ciascun controllo, inclusi stati (abilitato/disabilitato/evidenziato) e operazioni.
• Orientamenti supportati e transizioni tra di loro.
• Funzionalità rappresentata.
• Gestione degli errori.
• Dimensioni e vincoli.

Ecco i wireframe relativi alla mia ultima app iOS, NotifEye:

Se sei interessato, ho realizzato questi modelli usando lo strumento wireframing di Balsamiq.

Ad esempio, la descrizione dell'interfaccia utente potrebbe essere simile a:

• Barra di navigazione
  • Comando di navigazione a sinistra: torna alla home page
  • Barra del titolo: schermata corrente o nome dell'operazione
  • Nuovo pulsante: crea una nuova cosa
• Vista tabella
  • Sezione 0: Titolo della sezione
  • Righe della sezione 0:
    • Controllo riga 0 (ad es. immagine)
    • Riga di testo 0
    • Riga di testo 2

Pietre miliari

Come descritto sopra, i termini per il completamento e le consegne previste.

Ad esempio, la sezione delle pietre miliari nel modello del documento di progettazione potrebbe essere simile a:

1. Applicazione di facciata che mostra lo schermo e con transizioni temporanee e immagini/testo di esempio
2. Protocollo di comunicazione: l'applicazione si connette alla rete/server
3. Traguardo funzionale 1: …
4. Applicazione Alpha (con funzionalità complete)
5. Stabilità
6. Pubblicazione

Assicurarsi che la documentazione del software rimanga rilevante

Non intendo implicare che la fase di progettazione sia finita una volta che tu e il tuo cliente avete concordato un documento di specifica. Ci saranno sempre dettagli che nessuno di voi due aveva preso in considerazione, e sia voi che il cliente, guardando i risultati intermedi, incontrerete nuove idee, modifiche al design, difetti di progettazione imprevisti e suggerimenti impraticabili.

Il design si evolverà e le modifiche dovrebbero essere acquisite nel documento. Nei miei 25 anni di esperienza, non ho mai lavorato a un progetto in cui ciò non accadesse, e ciò include le mie applicazioni (ovvero, dove ero il mio cliente). Anche allora, ho creato un documento di progettazione con specifiche dettagliate e l'ho modificato secondo necessità.

Soprattutto, resta in contatto. Almeno più volte alla settimana, contatta il tuo cliente, riferisci sui tuoi progressi, chiedi chiarimenti e assicurati di condividere visioni identiche. Come cartina di tornasole per la tua comunicazione, cerca di assicurarti che tu e il tuo cliente diate le stesse risposte a queste tre domande:

1. A cosa stava lavorando lo sviluppatore?
2. A cosa sta attualmente lavorando lo sviluppatore?
3. Su cosa lavorerà lo sviluppatore dopo?