Attualmente sto revisionando un numero di modelli di documenti per la mia azienda. Una cosa che non abbiamo mai avuto è una specifica di architettura formale, quindi sto iniziando a metterne una.
Che tipo di cose inserisci nelle tue specifiche di architettura? Sentiti libero di copiare e incollare un sommario: sarebbe utile. Ci sono dei buoni modelli già disponibili sul web?
Ho modellato i miei Documenti sull'architettura del software (o SAD, che è un doppio senso perché è sia l'acronimo che cosa sentono gli sviluppatori dopo averli guardati) - dopo il Documento di architettura del software .
Fornisce un buon modello per spiegare l'architettura di alto livello e alcuni indicatori / descrizioni di cosa dovrebbe andare dove. In realtà ho trovato l'intera suite di modelli RUP inestimabile quando usato correttamente (non abbiate paura di modificare i documenti e modellarlo dopo le informazioni che ritieni utili.
Diverso da quello: un diagramma UML di alto livello dei componenti / pacchetti generali del sistema. Quindi importanti sottocomponenti (diagrammi di classe), e se sufficientemente complessi, alcuni diagrammi di sequenza che descrivono le interazioni importanti tra i compontenti.
L'importante è mantenere un equilibrio tra utilità, brevità e manutenibilità: non farti coinvolgere da dettagli inutili.
Quanto spesso vedi cambiare la tua architettura? La tua squadra aggiornerà religiosamente il documento con ogni refactoring / nuova funzione? Il documento durerà per tutta la vita del progetto? Quanto è grande la tua squadra? Chi è il pubblico? Per quali dettagli vuoi documentare?
Nella mia esperienza, i documenti architettonici formali di una squadra tendono a svanire molto presto. Quando tutti i membri del team si conoscono e la squadra è piccola, io tendo ad evitare questi documenti. Non sono aggiornati e portano fuori strada nuovi sviluppatori. I documenti sono eeevil. Un solido team che comunica apertamente tra loro supera ogni giorno i documenti di architettura formale.
A un certo punto, la comunicazione da persona a persona non può essere scalata. Ora devi scegliere correttamente il livello di eeevil documentazione che si applica alle dimensioni e all'ambito del tuo progetto. Ricorda troppe formalità significherà cambiare i documenti diventa troppo ingombrante. È possibile documentare così tanti dettagli che il mantenimento dei documenti diventa oneroso. Ricevi documenti scaduti che non sono aggiornati troppo a lungo. Troppo poca formalità significa che il team di Seatle non ha idea di cosa stia succedendo.
I team di medie dimensioni potrebbero fare bene con un wiki. Squadre molto grandi potrebbero desiderare di avere personale di documentazione a tempo pieno che aiuti a mantenere una documentazione estremamente formale. A questo punto, la documentazione dovrebbe essere più che utile e il team dovrebbe renderlo obbligatorio.
Leggi altre domande sui tag architecture documentation