Sono uno studente laureato in ingegneria aerospaziale. Gran parte della mia tesi di Master è stata dedicata allo sviluppo di un'architettura software OOP in MATLAB per facilitare il controllo di veicoli basati su Arduino (dirigibili, macchine, quadroni, ecc.).
Tutto il mio codice è molto documentato, ma la mia tesi stessa deve essere più che un riferimento di ogni classe e metodo - ha bisogno di descrivere ad un alto livello come ogni pezzo lavora insieme, e perché la mia architettura è così com'è.
Ho solo un minimo di ingegneria del computer e mi considero un programmatore abbastanza competente, ma non ho esperienza nella scrittura di questo tipo di documento. Quali tipi di cose devono essere inclusi nel documento? (Diagrammi, spiegazioni di paragrafo su come funziona ogni classe, ecc.)? Non voglio semplicemente ripetere i miei commenti al codice (sebbene all'inizio di ogni file ci siano paragrafi di commenti su come quella classe si rapporta ad altre classi). Mi chiedo anche se sia necessario diventare piuttosto tecnici (implemento alcuni concetti MATLAB piuttosto avanzati [cioè avanzati per ingegneri non informatici] come ascoltatori e callback); il mio pubblico proviene anche da un background di ingegneria aerospaziale.
Gli esempi sarebbero apprezzati se esistessero.
EDIT : la parte che interessa davvero al mio pubblico non è l'architettura del software (le cose che questa domanda comporta); questo documento è per le persone che useranno il mio lavoro in futuro, che sono non ingegneri informatici! Quindi immagino che la domanda principale sia: cosa deve essere nel documento in modo tale che le persone che non sono in grado di accelerare il progetto (e possiamo assumerci la competenza della lingua) possano capire l'architettura, mantenere e utilizzare il software?