Creazione di un nuovo formato di file: scrivere prima il codice o la documentazione?

Stai confondendo documentazione con la specifica .

La specifica è il processo (di solito collaborativo) attraverso il quale la definizione di ciò che il formato dovrebbe fare e come un'applicazione ipotetica dovrebbe gestirlo, renderlo o analizzarlo.

È un processo di progettazione come quello che W3C fa durante la creazione delle specifiche HTML o CSS prima che i browser lo implementino.

Ovviamente il prodotto di questo processo può essere inteso come "documentazione", ma non è la documentazione di un'applicazione.

Se si sta creando un nuovo formato di file, discutere e progettare le specifiche.

Quindi codifica l'applicazione che utilizza quel formato di file (o chiedi ad altri di codificarlo).

Ma per creare un nuovo formato di file non è necessario scrivere una singola riga di codice. La specifica potrebbe non essere mai implementata, tuttavia esiste come una specifica.

Ovviamente quando una specifica viene implementata, viene rivista ed estesa con il feedback degli implementatori.

La documentazione che dovrebbe venire prima è quella che specifica ciò che il formato deve realizzare . Se l'utente deve essere in grado di specificare le dimensioni del testo, il colore, i collegamenti e averli riprodotti, tutte queste informazioni devono venire prima. Questo è distinto dal documentare come è stato implementato . Come hai detto, questo tipo di documento tecnico è difficile da scrivere completamente in anticipo, dal momento che non puoi prevedere tutte le conseguenze delle decisioni che prendi subito. La mia esperienza è che è meglio interlacciare entrambe le attività e completare la documentazione tecnica contemporaneamente all'implementazione di riferimento e alla suite di test.

Questa è davvero una questione di processo di sviluppo e metodologia di sviluppo. Qualsiasi approccio può essere ugualmente valido, ma alcuni potrebbero funzionare meglio nella tua organizzazione rispetto ad altri.

Sono un fan dei processi agili e non sono un grande fan della documentazione completa. La documentazione ha la tendenza a costare di più per scrivere rispetto ai benefici che si ottengono dalle persone che la leggono (che tendono a non fare), e ha la tendenza a diventare obsolete più rapidamente di quanto possa essere scritto.

Invece scriverei le specifiche eseguibili usando specifica per esempio . Vari strumenti supportano questo, ad es. FIT o Cetriolo. Quindi inizi a scrivere un po 'di specifiche e poi scrivi il codice sufficiente per soddisfare questa specifica. Poi un po 'più di specifiche, ecc.

Alla fine, ottieni una documentazione vivente, che può essere verificata per riflettere sempre ciò che effettivamente fa il sistema.