Come documentare le regole aziendali

Mi chiedo quale sarebbe il metodo formale e più comunemente praticato per documentare le regole aziendali? Inoltre, come documentare le specifiche dell'interfaccia utente degli artefatti di sviluppo (ad es. Documentare i campi modulo e come si comportano i pulsanti sul modulo, il testo informativo ... ecc.)

Per quanto riguarda le regole aziendali, penso che @Joppe abbia sottolineato l'UML che tutti stavamo pensando.

Use Case Diagrams offre un'eccellente panoramica di come attori / ruoli interagiscono con il sistema e quale sistema fa. Per casi d'uso complessi, informazioni aggiuntive spiegate testualmente aiuteranno molto ( precondizioni , postcondizioni , dipendenze su precedenti esecuzioni UC , ecc. )

Ci sono diagrammi che fanno anche grandi panoramiche del business a diversi livelli:

• Diagramma della macchina a stati se c'è qualche tipo di stato da documentare.
• Diagramma di attività . Per casi complessi, potrebbe essere necessario approfondire i dettagli. Il livello dei dettagli dipende da te e dipende da chi leggerà la documentazione. Questa potrebbe non sembrare una documentazione professionale, ma con il giusto livello di dettagli potrebbe diventare così.

Solo un consiglio, assegna un codice a ciascun caso d'uso (es. UC-1 , UC-n ). Questi saranno utili in seguito, durante la documentazione dell'interfaccia utente.

Per la documentazione dell'interfaccia utente la pratica comune (in questi giorni) è quella di fare wireframe . Abbastanza meglio delle schermate perché sembra più pulito e semplice. Ad esempio, dai un'occhiata a WireframeSketcher

Wireframes potrebbe non essere una documentazione sufficiente, quindi per ogni schermata fai una breve introduzione e descrivi ogni pulsante. Inoltre, fai riferimenti all'UC coinvolto nella schermata ( vedi ora perché i codici UC sono utili ). Ciò renderà coerente la tua documentazione.

Il punto di strumenti come Wireframesketcher è che fanno modelli interattivi. Perfetto per dare qualcosa di interattivo al cliente mentre stai ancora progettando o sviluppando.

Non dimenticare di documentare il piano di navigazione . Nav. Il piano non ha un diagramma UML, ma è possibile utilizzare invece Diagramma macchina a stati. Non è per quello che è stato fatto, ma comunque.

Infine, tieni a mente a chi ti stai rivolgendo.

• Tecnico : puoi approfondire i dettagli e utilizzare i tecnicismi.

• Non tecnico : evitare i tecnicismi (né relativi al linguaggio né al codice). Cerca di essere chiaro e semplice e usa gli stessi termini / parole usati dal cliente. Pensa come se non avessi idea della programmazione.

La documentazione viene spesso fatta in casi d'uso e altri moduli di prosa. Inoltre, può essere estremamente utile avere diagrammi UML e altre forme grafiche che ti offrano una panoramica a un livello superiore e siano facili da comprendere in un tempo inferiore rispetto alla lettura di pagine e pagine.

E, ultimo ma non meno importante, la migliore documentazione relativa sono casi di test che eseguono le regole aziendali. In questo modo puoi modificare il codice e scoprire che stai violando una regola aziendale. In caso contrario, la documentazione rischia sempre di diventare obsoleta e obsoleta.

Probabilmente la forma più comune è Casi d'uso . Puoi completarli con modelli e descrizioni di schermate.

Un libro che consiglierei è "Scrivere casi d'uso efficaci" di Alistair Cockburn. Descrive come è possibile scrivere casi d'uso a vari livelli di dettaglio, come evitare di cadere nell'approccio guidato dal "modello" e attenersi semplicemente alla documentazione dei bit necessari e pertinenti.

Qualunque metodo tu usi, assicurati che possano essere attivamente mantenuti. Dovrebbero essere documenti viventi. Ospitare i documenti in un sistema di controllo versione o in una sorta di sistema di gestione dei documenti come Sharepoint, può fare molto per mantenerli mantenuti. Tenere traccia delle regole aziendali attraverso i documenti di Word allegati alle e-mail è un modo orribile per affrontare il problema, poiché porta a più versioni fluttuanti.

Consiglio vivamente di separare rigorosamente le regole aziendali dalle specifiche di sistema facendo riferimento solo alle regole aziendali dal caso d'uso e dalla progettazione dell'interfaccia utente. La mia tecnica preferita è: - Avere un elenco di regole aziendali identificate in un foglio di calcolo. - Nella progettazione del sistema, utilizzare le specifiche del caso, le storie utente o altro, è sufficiente specificare "L'utente inserisce le informazioni come specificato nella regola aziendale BR012", "Il sistema calcola l'importo totale come specificato nella regola aziendale BR510". Raccomando questo articolo http://www.allaboutrequirements.com/business-rules/

Prova a generare il diagramma UML usando il codice Visual Studio e il plug-in Plant UML