Gestione della scrittura delle specifiche

9

Semplicemente non riesco a immaginare di scrivere software senza una specifica. Indipendentemente da quanto sia abbozzato o di alto livello, le specifiche sono importanti per spiegare ai programmatori che non sanno quali sono le funzionalità del programma.

Ma il problema con le specifiche è che è in qualche modo un cittadino di seconda classe nell'intero ciclo di sviluppo del software; quando lo sviluppo raccoglie il vapore, viene trascurato. Ma quando sorgono controversie, gli sviluppatori, i tester e le vendite si affretteranno a trovare le specifiche per giustificare i loro motivi.

Si verificheranno uno o più scenari:

La specifica non può essere recuperata, nessuno sa dove si trova la specifica
Diverse versioni delle specifiche emergono da fonti diverse; ci vogliono grandi difficoltà per scoprire quale versione è l'ultima o se è disponibile una versione più recente.
La specifica è incompleta, mancano alcune parti dei documenti a cui fa riferimento.

Quindi la gestione delle specifiche è importante ed è altrettanto importante che tutti abbiano una sola fonte di specifiche.

Come gestite le vostre specifiche? Ho cercato di convincere tutti a utilizzare Google Documenti, ma tutti hanno obiettato. Tutti sono semplicemente troppo attaccati e innamorati di Microsoft Word, che è - a loro avviso - molto facile da usare, molto facile da inserire immagine, molto facile da scrivere equazione e quant'altro.

Come convincerli che MS Word è terribile per la condivisione?

specifications

— Graviton
fonte

6

Come convincerli che MS Word è terribile per la condivisione?

Non perdere tempo.

Primo. Le specifiche dovrebbero essere in testo normale (in realtà) e sotto il controllo del codice sorgente. Usa Markdown o RST o qualche altro strumento di markup leggero per produrre una pagina PDF o HTML. Testo semplice.

Secondo. Prendi le varie fonti. Uniscili. Scrivi il tuo documento finale.

Quando obiettano, hanno due scelte.

Utilizza Google Documenti (o lo strumento di controllo del codice sorgente) per modificare la tua versione.
Continua a inviarti le modifiche che modifichi, filtra e trasformi nel documento finale.

Preferisco il n. 2. Qualcuno deve "possedere" le specifiche. E un gruppo di persone (stile wiki) conduce a dibattiti e guerre di cambiamento e documenti collaterali e conversazioni off-line e simili.

— S. Lott
fonte

1

+1 e ricorda la regola del minimo potere : chiunque desideri una versione elaborata in un editor WYSIWYG può semplicemente copiare il markup renderizzato.

— l0b0,

@ l0b0: bel link.

— S. Lott,

6

Non penso che sia un problema di "strumento", ma piuttosto un problema di "processo" (o mancanza di processo).

Probabilmente hai già un processo per rilasciare software (unit test, test di integrazione, lettera di rilascio, consegna, ecc.), Devi implementare anche un processo di documentazione.

Chi scriverà le specifiche? Chi li aggiornerà o li manterrà?
Chi esaminerà le specifiche?
Chi approverà le specifiche? Architetto, capo progetto, QA?
Come vengono archiviate le specifiche?
Chi si accerterà che non vengano utilizzate versioni obsolete?

— Xavier T.
fonte

2

+1: i problemi degli utensili sono spesso sintomi di problemi di processo.

— S. Lott,

abbiamo un processo, ma la gente ama solo lamentarsi del fatto che il processo non funziona e tagliare angoli ogni volta che è possibile.

— Graviton,

@Graviton: il tuo problema principale è probabilmente che la direzione non può vedere l'uso della documentazione e quindi non applicare regole rigide. Se vuoi che le cose migliorino, probabilmente dovrai mostrare loro quanto sia importante.

— Xavier T.

4

Un certo tipo di controllo è sicuramente richiesto.

Deve essere aggiornato e firmato, e questo processo deve essere rigoroso.

In troppi posti, la firma viene trascurata e questo porta a battaglie tra i panini.

La posizione non ha importanza finché può essere monitorata

Sharepoint
un'unità condivisa protetta e con backup
Ho visto alcuni posti usare il loro controllo del codice sorgente !!

Ma soprattutto, è necessario acquistare da tutte le persone coinvolte e 1 o 2 persone che hanno la responsabilità di gestire sia il documento che la firma, ad es. il Project Manager.

— OZZ
fonte

+1, consiglio vivamente di spostare il documento di specifica nel controllo del codice sorgente se nient'altro aiuta. Un vantaggio è ottenere la cronologia delle versioni. Anche se non riesci a fare le differenze di versione (a meno che non trovi un plug-in in grado di fare differenze sui file di Word) puoi comunque estrarre tutte le versioni e vedere cosa è cambiato. Questo può essere MOLTO utile in una disputa sulle specifiche. Anche l'approvazione è molto buona. E anche l'importanza di coinvolgere tutti nel processo (quindi nessuno può dire "quando è stato deciso?") Non può essere sottolineato abbastanza.

— FrustratedWithFormsDesigner,

0

MS Word è perfetto per creare una specifica. Gestiamo i nostri in SharePoint, che gestisce anche il controllo delle versioni. Se non hai a portata di mano SharePoint o un altro prodotto per la gestione dei documenti, Google Documenti è OK (ora puoi caricare file .doc / .docx senza convertirli nel formato di Google Documenti). O come altri hanno suggerito, puoi persino memorizzarli nel tuo sistema di controllo della versione del codice sorgente (se le persone che creano le specifiche hanno accesso a quel sistema).

— Marcie
fonte

0

 > How to convince them that MS Word is just terrible for sharing?

non è possibile confrontare facilmente qual è la differenza tra due istanze in un sistema di controllo della versione.

Non mi piacciono le specifiche delle parole per quel motivo. Ma dato che è una decisione politica di usare le specifiche delle parole, abbiamo come prima pagina "informazioni sulla storia" con queste colonne:

numero-versione (riferito alla verifica del prodotto), autore, data, descrizione

— k3b
fonte