L'approccio di alto livello che generalmente prendo quando documento le architetture (o anche progetti più dettagliati, di livello inferiore) è:
- Identificare le parti interessate al progetto. Il team di ingegnerizzazione/sviluppo è una delle parti interessate. Il team di test/assicurazione della qualità, il team dell'infrastruttura IT, la gestione del progetto e forse il personale di supporto possono essere anch'essi stakeholder del sistema e interessati a vari aspetti del progetto.
- Identificare le aree di interesse nel vostro sistema. Se il vostro sistema ha un database, un punto di vista è la struttura del database. Se hai un sistema distribuito, allora gli amministratori di sistema o il personale del servizio clienti potrebbero essere interessati a dove sono installati i componenti. Se avete un'interfaccia pubblica, allora gli sviluppatori esterni sono interessati a cosa sia quell'interfaccia - formati di file, formati di dati, ecc. Se avete molti algoritmi complessi, allora i progettisti/manutentori di algoritmi sono interessati ai flussi di lavoro e ai passi dell'algoritmo. Ogni punto di vista che identifichi è un insieme specifico di preoccupazioni.
- Per ogni punto di vista che hai, scegli una rappresentazione appropriata. Per il punto di vista del database, forse i diagrammi entità-relazione e un dizionario dei dati possono essere utili. Per le interfacce pubbliche, i documenti XML Schema o la documentazione API possono essere inclusi come parte della vostra documentazione. Per algoritmi complessi, considerate i diagrammi di attività o di interazione UML. Quando si sceglie una notazione, preferisco notazioni ben conosciute e ben definite in modo da non dover spiegare la mia notazione a qualcun altro e poterlo semplicemente indirizzare al materiale di riferimento esistente se non conosce i simboli usati.
- Aggiungi descrizioni testuali e razionali intorno ai diagrammi. Spiega non solo quali sono state le decisioni architettoniche che hai preso, ma cosa ti ha spinto a prendere quelle decisioni.
I framework architettonici, come lo Zachman Framework, The Open Group Architectural Framework, il Department of Defense Architectural Framework, e altri framework architettonici aiutano definendo punti di vista essenziali e punti di vista che sono generalmente applicabili.
In definitiva, la "migliore" documentazione è quella che soddisfa i bisogni degli stakeholders. Identificare chi ha bisogno delle informazioni e di cosa hanno bisogno esattamente è il primo passo.