Dipende un po 'dal pubblico di destinazione, ma la mia esperienza (più nello sviluppo su piccola / media scala rispetto a lavori su larga scala) è che i documenti di progettazione dettagliata sono ardui e noiosi da scrivere, raramente letti e tendono a finire fuori data entro la data di consegna di un progetto.
Questo non significa che siano inutili - se stai offrendo qualcosa per qualcuno, ci deve essere una dichiarazione autorevole e concordata di ciò che verrà consegnato sufficientemente dettagliato che tutti possono indicarlo nel caso in cui qualcuno non sia soddisfatto dell'affare e dire "questo è ciò che abbiamo promesso" e valutarlo rispetto a ciò che è stato consegnato.
Se dovessi creare un'azienda per costruire un prodotto, tuttavia, non mi preoccuperei molto di una specifica dettagliata. Vorrei documentare cosa avremmo intenzione di fare, ma non vorrei entrare troppo in profondità per quanto riguarda come - questa è la parte che più probabilmente cambiare e lasciare i documenti obsoleti e inutili o addirittura inaccurati per essere effettivamente ostruzionistici. Preferirei documentare il "come" roba nel codice usando qualsiasi formato di documentazione che la lingua o l'IDE supporti meglio, così come il codice cambia è più facile aggiornare la documentazione allo stesso tempo. Non si fermerà perché non sarà aggiornato, ma lo ridurrà un po '.
Idealmente vorresti un documento di design che possa raddoppiare il tuo manuale quando il tuo codice è completo, ma non conosco nessuno che lo abbia gestito con successo.