![Lo stato dell'arte sulla documentazione dei progetti ICT
Due pratiche importanti
Executable specifications, for example [...] a developer test-
suite [...]. Because these artifacts add value there is a
significantly greater chance that developers will keep them up-
to-date.
86
Agile/Lean Documentation: Strategies for Agile Software Development by Scott W. Ambler,
http://www.agilemodeling.com/essays/agileDocumentation.htm#IssuesWithDocumentation
Document stable concepts, not speculative concepts, and
thereby document as late as possible in the life cycle.
Agile/Lean Documentation: Strategies for Agile Software Development by Scott W. Ambler,
http://www.agilemodeling.com/essays/agileDocumentation.htm#WhenToCreateDocumentation](https://image.slidesharecdn.com/lostatodellartesulladocumentazionedeiprogettiict-170605093253/85/Lo-stato-dell-arte-sulla-documentazione-dei-progetti-ICT-86-320.jpg)
Lo stato dell' arte sulla documentazione dei progetti ICT
- 1. Lo stato dell'arte sulla documentazione dei progetti ICT Lo stato dell'arte sulla documentazione dei progetti ICT Ing. Matteo Gentile gentile.matteo@gmail.com https://it.linkedin.com/in/gentilematteo Ordine degli Ingegneri di Genova 19 Maggio 2017
- 2. Lo stato dell'arte sulla documentazione dei progetti ICT Presentazione Ogni progetto informatico 竪 sicuramente incompleto fino a quando non viene corredato da una documentazione esauriente. In un progetto informatico la documentazione 竪 presente in tutte le fasi, dalla raccolta dei requisiti, passando per la documentazione di analisi e tecnica di implementazione, fino ad arrivare alla documentazione per lutente finale. Quali documenti 竪 opportuno generare in un progetto ? La documentazione di progetto va generata allinizio o alla fine ? Come fare a tenere sempre aggiornata la documentazione quando i requisiti o le implementazioni cambiano ? Che standard usare per creare una buona documentazione di un progetto informatico ? Recentemente c竪 stata un'ampia diffusione delle metodologie Agili. E vero che non 竪 prevista documentazione ? Questo evento nasce per rispondere a queste domande e per mostrare attraverso un esempio pratico come introdurre la documentazione in un progetto che usa le metodologie Agili. 2
- 3. Lo stato dell'arte sulla documentazione dei progetti ICT Agenda La documentazione nei progetti ICT Documentare nel mondo Agile Esempio di approccio 3
- 4. Lo stato dell'arte sulla documentazione dei progetti ICT Introduzione alla documentazione nei progetti ICT Se chiedete ad un ingegnere di mostrare la struttura di un edificio e documentarla egli vi presenter planimetrie del sito, dei piani della struttura, viste di elevazione, sezioni, disegni dettagliati, ecc. 4 Plans and elevations of Bedford Park Estate, Turnham Green, London, 1877 - Catalogue reference COPY 1/39 folio 347.
- 5. Lo stato dell'arte sulla documentazione dei progetti ICT Introduzione alla documentazione nei progetti ICT Se chiedete a un ingegnere del software di mostrarvi e documentarvi larchitettura di un sistema con dei diagrammi otterrete un insieme vario di 束scatole e linee損 di diverso tipo e dettaglio, e probabilmente se lo chiederete a mille persone diverse otterrete mille schemi e documenti differenti. 5 http://www.bredemeyer.com/
- 6. Lo stato dell'arte sulla documentazione dei progetti ICT 6 User Interface Business Logic Data User Interface MAGIC Il vostro software Come lo vede lutente
- 7. Lo stato dell'arte sulla documentazione dei progetti ICT Tipologia di documentazione approccio "classico" Requisiti: attributi, capacit, caratteristiche, standard seguiti, qualit del sistema Analisi e Progettazione: relazione tra sw ed esterno, tra le componenti interne, principi sw usati per i componenti, Software Design Specificaion Documentazione tecnica: Software Detailed Design Specification, documentazione API, algoritmi Documentazione di test: scrittura test case, test automatici e manuali, performance test Documentazione utente: user manual, help on line, corsi, release notes Documentazione di qualit: se adottiamo standard Marketing: pubblicizzazione prodotto, analisi di mercato 7
- 8. Lo stato dell'arte sulla documentazione dei progetti ICT Requisito Definizione Formale Un requisito 竪 una propriet o una qualit che un prodotto software deve avere o soddisfare per soddisfare un contratto, uno standard, una specifica o altri documenti formali (IEEE 610.12- 1990, IEEE Standard Glossary of Software Engineering Terminology ). Definizione Breve Una propriet o una qualit di un sistema 8 RequirementsUser Story
- 9. Lo stato dell'arte sulla documentazione dei progetti ICT Raccolta ed elicitazione dei Requisiti Lelicitazione dei requisiti (requirement elicitation) 竪 un insieme di diverse tecniche, combinate fra loro, per riuscire ad estrarre dalla mente del cliente o committente le idee per capire cosa il software oggetto del contratto dovr fare. 9
- 10. Lo stato dell'arte sulla documentazione dei progetti ICT Raccolta requisiti ed Analisi Le tecniche di elicitazione pi湛 usate sono: le interviste, durante le quali si pongono alle persone del cliente domande esplicite; losservazione, durante la quale si osservano sul campo le funzioni svolte in cui il software dovr intervenire; il gruppo di lavoro (brainstorming). 10 IIBA, A Guide to the Business Analysis Body of Knowledge速 (BABOK速 Guide)
- 11. Lo stato dell'arte sulla documentazione dei progetti ICT Raccolta requisiti ed analisi Analisi dei requisiti Serve per descrivere in modo formale e preciso i requisiti che dovr avere il sistema oggetto del progetto. 11 Propagazione errori
- 12. Lo stato dell'arte sulla documentazione dei progetti ICT Raccolta requisiti ed analisi 12
- 13. Lo stato dell'arte sulla documentazione dei progetti ICT Obiettivo analisi Produrre una descrizione completa formalizzata lato utente, con il giusto livello di dettaglio, di : tutto ci嘆 che il sistema deve fare (requisiti funzionali), dellambiente in cui dovr operare (requisiti non funzionali) dei vincoli che dovr rispettare. Usando anche diagrammi UML A meno di Agile Methodologies (come vedremo) 13 Features
- 14. Lo stato dell'arte sulla documentazione dei progetti ICT Fase di progettazione 14 Richiede particolare attenzione
- 15. Lo stato dell'arte sulla documentazione dei progetti ICT Fase di progettazione La fase di progettazione deve produrre le istruzioni operative per la realizzazione effettiva del progetto informatico (implementazione). Le istruzioni devono avere il giusto livello di dettaglio ed essere espresse in forma di documenti strutturati. Risultato: la definizione dellarchitettura del sistema i suoi componenti software le propriet visibili esternamente di ciascuno di essi (linterfaccia dei componenti) le relazioni fra le parti. Per la progettazione si possono usare diagrammi gli UML Activity Diagram (o BPMN ) 15
- 16. Lo stato dell'arte sulla documentazione dei progetti ICT Sviluppo - Documentazione tecnica E la fase principale e pu嘆 seguire diverse metodologie (waterfall, scrum, kanban , ) E possibile fornire ai clienti (se previsto) il sorgente, e quindi documentato. Documentazione API o chm generati con tool (Javadoc, Sandcastle, Ndoc, ) La Software Detailed Design Specification (SDDS) contiene la spiegazione di: implementazioni interne, strutture dati, algoritmi, tool e linguaggi usati 16 Tasks
- 17. Lo stato dell'arte sulla documentazione dei progetti ICT Sandcastle 17
- 18. Lo stato dell'arte sulla documentazione dei progetti ICT Documentazione tecnica e cambiamenti nel team 18
- 19. Lo stato dell'arte sulla documentazione dei progetti ICT Test e Delivery Test Report Unit Testing o Automated Tests Report Test Manuali eseguiti/falliti Report Test di performance Delivery Documentazione on line o inclusa nel setup (meglio "how to" piuttosto che spiegazione testuale) Release notes Corsi (on line o in aula) 19
- 20. Lo stato dell'arte sulla documentazione dei progetti ICT Fasi del progetto SW 20 Raccolta requisiti BPMN Testuale Analisi UML Use Case Diagram UML Activity Diagram Progettazione UML Class Diagram UML Sequence Diagram Implementazione Software Code documentation Test Test plan Unit Testing / TDD Performance Test Rilascio User manual Technical reference manual
- 21. Lo stato dell'arte sulla documentazione dei progetti ICT Standard di progetto - ISO/IEC 9001: Sistema di gestione per la qualit - ISO/IEC 90003: Applicazione della ISO/IEC 9001 al software - ISO/IEC 29110: Software Lifecycle Processes for VSE - ISO/IEC 29119: Software Testing - ISO/IEC/IEEE 29148-2011 : Systems and software engineering - Life cycle processes - Requirements engineering - ISO/IEC 9126: Modello della qualit del software - ISO/IEC 12207: Software Lifecycle Processes - ISO/IEC 15288: LCM - Lifecycle Processes - ISO/IEC 15289: Lifecycle Product Information Content (documentation) - ISO/IEC 15504: Software Process Assessment - ISO/IEC 16326: Project Management - ISO/IEC 19011: Guida alla conduzione degli audit dei sistemi di gestione - ISO/IEC 19759: Software Engineering Body of Knowledge (SWEBOK) - ISO/IEC 27001 e 27002: Information technology Security techniques Information security management systems Requirements 21
- 22. Lo stato dell'arte sulla documentazione dei progetti ICT Sicurezza 22 ISA/IEC-62443 (ISA-99) serie di standard che definisce procedure per implementare in modo elettronicamente sicuro gli Industrial Automation and Control Systems (IACS)
- 23. Lo stato dell'arte sulla documentazione dei progetti ICT UML 23
- 24. Lo stato dell'arte sulla documentazione dei progetti ICT UML 24 Famiglia di notazioni grafiche che si basano su un singolo meta-modello e servono a supportare la descrizione e il progetto dei sistemi software Martin Fowler Pensate su paradigma object oriented 1995 (v 0.9) 2011 (v 2.4.1)
- 25. Lo stato dell'arte sulla documentazione dei progetti ICT Structural Modeling Individuare e modellare gli elementi da mettere insieme per costruire il software necessario per risolvere il problema in esame E la parte statica Diagrammi: Class (vocabolario delle cose che costruiamo) Component (organizzazione logica delle parti del sistema) Package (organizzazione fisica delle parti del sistema) Deployment (mappatura delle componenti del sistema con quello che viene rilasciato) 25
- 26. Lo stato dell'arte sulla documentazione dei progetti ICT Behavioral Modeling Orientato alle funzionalit del sistema (processi, interazioni, azioni) E la parte dinamica Diagrammi Use Case (funzionalit sistema e attori) Sequence (sequenza temporale delle operazioni) State (stati degli oggetti e loro cambiamenti) Activity (flowcharts, funzionalit) 26
- 27. Lo stato dell'arte sulla documentazione dei progetti ICT UML descrive un sistema con tre modelli Modello funzionale (punto di vista utente, comportamento visto da fuori) Analisi dei requisiti Use Case Diagram Modello ad oggetti (struttura sistema) Analisi del dominio Class Diagram, Object Diagram, Deployment Diagram Modello dinamico (comportamento oggetti del sistema) Sequence Diagram, Activity Diagram, Statechart Diagram 27
- 28. Lo stato dell'arte sulla documentazione dei progetti ICT Esempi di uso Use Case Diagram: per capire nei dettagli cosa il sistema deve fare Activity/Statechart Diagram: per definire i processi fondamentali, ovvero mettere in ordine cronologico i casi duso definiti dagli Use Case Diagram Class/Object Diagram: per definire le entit fondamentali coinvolte nel funzionamento del sistema Communication (Collaboration) Diagram: per definire le interazioni fra le entit fondamentali Sequence Diagram: per definire la sequenza temporale delle interazioni fra entit Component Diagram: per definire nei dettagli quali parti compongono il sistema/prodotto software finito e le loro relazioni Deployment Diagram: per definire dove le varie parti di un programma devono essere poste in unarchitettura distribuita (es. client-server) 28
- 29. Lo stato dell'arte sulla documentazione dei progetti ICT Approccio ad UML Steve Mellon e Martin Fowler prevedono tre modi diversi di utilizzo: Abbozzo (sketch) Progetto (blueprint) Linguaggio di programmazione 29
- 30. Lo stato dell'arte sulla documentazione dei progetti ICT UML come abbozzo (Sketch) Informale Documentazione, discussione e condivisione delle idee Basso rigore formale Selettivit: focalizzazione solo su alcuni aspetti dellapplicazione Bassa, se non nulla dipendenza dal tool di modellazione 30
- 31. Lo stato dell'arte sulla documentazione dei progetti ICT UML come progetto (Blueprint) Alto rigore formale Completezza Forward e reverse engineering Forte dipendenza dal tool di modellazione 31
- 32. Lo stato dell'arte sulla documentazione dei progetti ICT UML come linguaggio di programmazione Utilizzare diagrammi per generare codice Fortissima dipendenza dal tool di modellazione 32
- 33. Lo stato dell'arte sulla documentazione dei progetti ICT UML nella documentazione di progetto Raccolta informale dei requisiti, comprensiva di tutti i requisiti funzionali e non Definizione dei criteri di accettazione Stesura dell analisi funzionale formalizzata con gli Use Case Definizione della cronologia delle interazioni (Activity Diagram), design delle interfacce utente e Diagramma di Navigazione (Mock-up) Definizione delle entit, delle relazioni che tra esse intercorrono e formalizzazione con il Class Diagram di analisi e la sua descrizione Design della base di dati (Modello E-R) e sua costruzione (e generazione degli script di creazione tabelle) 33
- 34. Lo stato dell'arte sulla documentazione dei progetti ICT Fasi che Compongono il Progetto Design architetturale del sistema Progettazione software e Class Diagram di Progetto Pianificazione delle attivit ed assegnamento degli incarichi, fatta attraverso strumenti di project management Sviluppo del software, seguendo le regole di stesura del codice definite a livello aziendale o di gruppo di sviluppo o uno degli standard presenti in letteratura Debug del software stendendo tracciando bachi sui problemi incontrati, in modo tale che possano servire daiuto in situazioni analoghe successive Documentazione Definizione delle procedure per linstallazione del software stesso (release notes). 34
- 35. Lo stato dell'arte sulla documentazione dei progetti ICT Raccolta dei Requisiti Iterazione 0 Ha in genere lo scopo di produrre un documento informale, scritto in linguaggio naturale, che spieghi molto brevemente gli obiettivi del cliente. Questo documento dovrebbe avere le seguenti caratteristiche: Indicare chi 竪 il cliente finale; Indicare i requisiti che il cliente richiede (situazione attuale e obiettivo atteso); Definire di che tipo di lavoro si tratta; Indicare (se esistono) vincoli imposti da altri software o sistemi o ambienti esistenti con cui si debba interoperare; Indicare requisiti non funzionali (es. numero di accessi simultanei, dimensioni della base dati, prestazioni attese, ...); Descrivere informalmente e a grandi linee il lavoro da svolgere. Riportare le fonti informative Descrivere a grandi linee requisiti e prime iterazioni previste 35
- 36. Lo stato dell'arte sulla documentazione dei progetti ICT Requisiti non funzionali - Vincoli Sono tutti quei requisiti che non riguardano le funzionalit del sistema, ma ne permettono o caratterizzano il funzionamento: Scalabilit Performance Supporto di Sistemi Operativi Supporto di browser (se necessario) Localizzazione Usabilit Standard usati, ad es. ISO 8601 per date, ISO/IEC 10646 (Unicode) per codifica testo, Supporto al cliente 36
- 37. Lo stato dell'arte sulla documentazione dei progetti ICT Progettazione SW nel passato Fino a circa la fine degli anni 90 si pensava di poter realizzare il software in modo simile ad un edificio 37
- 38. Lo stato dell'arte sulla documentazione dei progetti ICT Implementazione SW nel passato 38 Monkey Code
- 39. Lo stato dell'arte sulla documentazione dei progetti ICT 39
- 40. Lo stato dell'arte sulla documentazione dei progetti ICT Problemi Come riuscire ad aggiornare tutta la documentazione in sincronia con gli aggiornamenti tecnici di una o pi湛 parti ? Documentazione come fase iniziale e non finale del ciclo di vita del software pu嘆 essere 束pericolosa損. 40
- 41. Lo stato dell'arte sulla documentazione dei progetti ICT Application Lifecycle Management (ALM) Se utilizzate un ALM (come ad esempio Microsoft TFS) per il vostro progetto in cui inserite i requisiti e tutto quello che li riguardano, questo pu嘆 aiutarvi anche a creare la documentazione di progetto in automatico. Ad esempio esistono dei plugin per TFS che permettono di esportare/importare i Requirements e creare un documento MS Word. AIT WordToTFS Enhanced Export SmartWord4TFS 41
- 42. Lo stato dell'arte sulla documentazione dei progetti ICT TFS e Project Se usate Office Project per gestire il progetto, si pu嘆 facilmente creare un backlog, gli scheduled tasks, assegnare le risorse e tracciare il lavoro esportando anche in Team Services o Team Foundation Server (TFS). https://www.visualstudio.com/en-us/docs/work/office/create-your-backlog-tasks-using-project 42
- 43. Lo stato dell'arte sulla documentazione dei progetti ICT Esempio di share di progetto 43
- 44. Lo stato dell'arte sulla documentazione dei progetti ICT Agile 44
- 45. Lo stato dell'arte sulla documentazione dei progetti ICT Agile Manifesto 45 Importanti Individui e interazioni Software funzionante Collaborazione cliente Rispondere al cambiamento Piuttosto che Processi e strumenti Documentazione esaustiva Negoziazione contratti Seguire un piano Stiamo scoprendo modi migliori di creare software, sviluppandolo e aiutando gli altri a fare lo stesso. Grazie a questa attivit siamo arrivati a considerare Ovvero, fermo restando il valore delle voci a destra, consideriamo pi湛 importanti le voci a sinistra.
- 46. Lo stato dell'arte sulla documentazione dei progetti ICT Agile Software Development Poster 46
- 47. Lo stato dell'arte sulla documentazione dei progetti ICT Utilizzo di metodologie agili 47 9属 Annual state of Agile Survey 2015 VersionOne.com
- 48. Lo stato dell'arte sulla documentazione dei progetti ICT System Development LifeCycle (SDLC) 48
- 49. Lo stato dell'arte sulla documentazione dei progetti ICT SDLC Coverage nelle metodologie agili 49
- 50. Lo stato dell'arte sulla documentazione dei progetti ICT Agile Methodologies 50
- 51. Lo stato dell'arte sulla documentazione dei progetti ICT Waterfall vs Agile 51
- 52. Lo stato dell'arte sulla documentazione dei progetti ICT Design - Classic vs Agile 52 Classic Agile
- 53. Lo stato dell'arte sulla documentazione dei progetti ICT 53
- 54. Lo stato dell'arte sulla documentazione dei progetti ICT 54 https://toggl.com/developer-methods-infographic
- 55. Lo stato dell'arte sulla documentazione dei progetti ICT Waterfall 55
- 56. Lo stato dell'arte sulla documentazione dei progetti ICT Agile development 56
- 57. Lo stato dell'arte sulla documentazione dei progetti ICT Kanban 57
- 58. Lo stato dell'arte sulla documentazione dei progetti ICT Scrum 58
- 59. Lo stato dell'arte sulla documentazione dei progetti ICT Lean 59
- 60. Lo stato dell'arte sulla documentazione dei progetti ICT Agile Le decisioni sono prese solo quando ci sono abbastanza informazioni in modo da prendere la decisione giusta Vorremmo degli strumenti che permettano di pensare alla struttura senza forzarci ad una implementazione dettagliata perch辿 magari non si hanno tutte le informazioni, e senza stravolgerla quando vogliamo entrare nel dettaglio 60
- 61. Lo stato dell'arte sulla documentazione dei progetti ICT Feature Driven Development (FDD) Una metodologia agile, ideata da Jeff De Luca e Peter Coad, che propone una robusta fase di analisi e progettazione integrata con un modello di sviluppo agile ed 竪 guidata dalle funzionalit richieste e necessarie del programma. 61
- 62. Lo stato dell'arte sulla documentazione dei progetti ICT FDD I 5 processi di sviluppo 62 皹 IterazioneUML
- 63. Lo stato dell'arte sulla documentazione dei progetti ICT FDD I 5 processi di sviluppo 63
- 64. Lo stato dell'arte sulla documentazione dei progetti ICT Fasi di ogni Iterazione Kickoff Meeting del Package (viene chiarito ogni dettaglio delle funzionalit incluse) 1% Design (vengono definiti classi/metodi/documentazioni richiesti) 40% Design review (tutti gli attori dello sviluppo revisionano il progetto proposto) 3% Coding (con i relativi unit test) 45% Code review meeting (la revisione del codice viene effettuata da tutti i programmatori) 10% Release meeting (le funzionalit implementate vengono "promosse" al processo di integrazione) 1% 64
- 65. Lo stato dell'arte sulla documentazione dei progetti ICT Successo 65
- 66. Lo stato dell'arte sulla documentazione dei progetti ICT Successo McKinsey & Company 2012 - Progetti IT su larga scala (> 15 M$): - 17 % talmente fallimentari da mettere a rischio lesistenza della ditta software - 45 % fuori budget - 7 % ritardo - e il 56 % consegnano meno dellatteso ! Geneca 2011 studio su interviste: - 75 % partecipanti al progetto non ha fiducia nel successo - 78 % business non allineato coi requisiti di progetto PMG New Zealand 2010 sondaggio su 100 aziende sw di diverso tipo: - 70 % almeno 1 progetto IT fallito nellultimo anno - 50 % il progetto ha fallito nellottenere obiettivi richiesti 66 http://www.mokabyte.it/2014/09/fallimentoprogetti/
- 67. Lo stato dell'arte sulla documentazione dei progetti ICT Cause insuccesso Scopo / obiettivi non chiari 67 Pianificazione non adeguata (roadmap, studi di mercato, modelli di business, ) (stime errate, team inadeguato, vincoli esterni di fornitori )
- 68. Lo stato dell'arte sulla documentazione dei progetti ICT Cause insuccesso Scarso coinvolgimento stakeholder 68 (necessari input e feedback continui) Management inesperto (problemi organizzativi, conflitti)
- 69. Lo stato dell'arte sulla documentazione dei progetti ICT Stimare un progetto 69
- 70. Lo stato dell'arte sulla documentazione dei progetti ICT Agenda La documentazione nei progetti ICT Documentare nel mondo Agile Esempio di approccio 70
- 71. Lo stato dell'arte sulla documentazione dei progetti ICT Documentazione 71 Documentazione di Sistema Overview architettura Decisioni di design Documentazione requisiti critici Documentazione Utente Documentazione installazione Documentazione utilizzo Training
- 72. Lo stato dell'arte sulla documentazione dei progetti ICT Documentazione nel mondo Agile Non esiste una "definizione" di documentazione nel mondo Agile Dalla prospettiva dello sviluppo : la documentazione del codice Dalla prospettiva degli stakeholder: la documentazione del sistema Pi湛 in generale: documentazione software Termine che racchiude ogni documentazione di un prodotto software 72
- 73. Lo stato dell'arte sulla documentazione dei progetti ICT Documentazione Classificazione iniziale Prima dello sviluppo Durante lo sviluppo Alla fine dello sviluppo 73
- 74. Lo stato dell'arte sulla documentazione dei progetti ICT Visione Tecnica Digrammi architetturali di alto livello Visione Funzionale Epiche principali per identificare le caratteristiche principali del prodotto 74 Prima dellinizio
- 75. Lo stato dell'arte sulla documentazione dei progetti ICT Durante il progetto Visione Tecnica Test-Driven Development (TDD) Behaviour-Driven Development (BDD) Codice ben strutturato (SOLID) UML quando serve DoD (Definition of Done) 75 Visione Funzionale User story come documentazione Acceptance criteria chiari e completi Acceptance test case passati No Bug Severity 2 (o < 10%)
- 76. Lo stato dell'arte sulla documentazione dei progetti ICT Dopo lo sviluppo Visione Tecnica Il codice Documentazione codice & uso Tool (Sandcastle, Javadoc) Risultati test 76 Visione Funzionale Quanto richiede lo stakeholder Come richiede lo stakeholder (corsi, documenti, supporto, )
- 77. Lo stato dell'arte sulla documentazione dei progetti ICT Dove e quando documentare 77 Dove Repository accessibile e aggiornabile con facilit Quando Produrre documentazione in modo incrementale Ogni increment
- 78. Lo stato dell'arte sulla documentazione dei progetti ICT Agile Modeling Agile Modeling Scott W. Ambler http://www.agilemodeling.com 78
- 79. Lo stato dell'arte sulla documentazione dei progetti ICT Le relazioni 79 Modello Documento Software Documentazione pu嘆 far parte di un contiene descrivepu嘆 descrivere 竪 http://www.agilemodeling.com/essays/agileDocumentation.htm#CriticalPoints
- 80. Lo stato dell'arte sulla documentazione dei progetti ICT Perch辿 documentare nel mondo Agile ? Lo chiedono gli stakeholder (come ho speso il mio denaro !) Per definire un modello di contratto per le iterazioni con lesterno Per supportare la comunicazione con gruppi esterni Per non dimenticare (abbastanza documentazione per operare, supportare e mantenere sw nel tempo) Per processi di Audit Per capire meglio e analizzare parti complesse 80
- 81. Lo stato dell'arte sulla documentazione dei progetti ICT Ciclo di vita di un modello Agile 81
- 82. Lo stato dell'arte sulla documentazione dei progetti ICT Problemi associati alla documentazione SW development vs documentation development : bilanciare il tempo e gli sforzi per avere feedback senza sprecare tempo Specifiche "eseguibili" meglio che doc statica : se posso creare suite di test che testa le specifiche o parte di esse posso validarle sempre Sviluppatori hanno la conoscenza, i technical writers lo skill : dev iniziano a scrivere o aiutano allinizio chi fa doc Doc richiesta a fine progetto pu嘆 essere diversa : si pu嘆 integrare a fine sviluppi e documentando quando uno sprint 竪 finito evita modifiche continue Code documentation vs external documentation : "Single Source Information" devo cercare di documentare dove serve e non in modo "doppio" Project level vs Enterprise level documentation : alcuni documenti non sono per il progetto o il team, ma destinati allintera organizzazione (burocrazia) Quantit vs qualit : meglio poca documentazione non contenente errori che molta sbagliata o non aggiornata 82
- 83. Lo stato dell'arte sulla documentazione dei progetti ICT Quando documentare in Agile Beneficio massimizza il ROI dello stakeholder : beneficio 竪 pi湛 grande del costo di creazione e manteniimento. Se un documento utente fornisce il 50% di ROI e un corso agli utenti il 100% scegliere il corso Stakeholders conoscono il TCO del doc : il Total Cost of Ownership deve essere noto "Lean and sufficient" Documento pi湛 semplice possibile (es: per punti invece che in prosa) Documenti servono a uno scopo se non sai a cosa serve, non creare un documento "Cose utili da sapere" Non devono contenere informazioni ovvie. ES: la tabella Clienti contiene una colonna NAME che 竪 il nome del cliente Facilita luso dei clienti lavorare insieme al cliente per conoscere le sue necessit di documentazione Documentazione 竪 sufficientemente accurata, consistente, dettagliata Se ho pi湛 versioni di sw, nellultima documento tutto non solo le novit e se ci sono modifiche devo aggiornarla. La documentazione non deve essere perfetta ma abbastanza buona. 83
- 84. Lo stato dell'arte sulla documentazione dei progetti ICT Il valore pi湛 importante The fundamental issue is communication, not documentation. 84 Agile/Lean Documentation: Strategies for Agile Software Development by Scott W. Ambler, http://www.agilemodeling.com/essays/agileDocumentation.htm#CriticalPoints
- 85. Lo stato dell'arte sulla documentazione dei progetti ICT Il principio pi湛 importante Travel Light. Every artifact that you create, and then decide to keep, will need to be maintained over time. 85 Agile Modeling (AM) Principles v2 by Scott W. Ambler, http://www.agilemodeling.com/principles.htm#TravelLight
- 86. Lo stato dell'arte sulla documentazione dei progetti ICT Due pratiche importanti Executable specifications, for example [...] a developer test- suite [...]. Because these artifacts add value there is a significantly greater chance that developers will keep them up- to-date. 86 Agile/Lean Documentation: Strategies for Agile Software Development by Scott W. Ambler, http://www.agilemodeling.com/essays/agileDocumentation.htm#IssuesWithDocumentation Document stable concepts, not speculative concepts, and thereby document as late as possible in the life cycle. Agile/Lean Documentation: Strategies for Agile Software Development by Scott W. Ambler, http://www.agilemodeling.com/essays/agileDocumentation.htm#WhenToCreateDocumentation
- 87. Lo stato dell'arte sulla documentazione dei progetti ICT Model Driven Development (MDD) Modelli estensivi e completi sono creati prima di implementare il codice. Un esempio 竪 lo standard Model Driven Architecture di OMG. 87
- 88. Lo stato dell'arte sulla documentazione dei progetti ICT Agile Model Driven Development (AMDD) Versione Agile di MDD. 88 Modelli Estensivi Modelli Agili Modelli abbastanza accurati per guidare lo sviluppo.
- 89. Lo stato dell'arte sulla documentazione dei progetti ICT AMDD Lifecycle 89
- 90. Lo stato dell'arte sulla documentazione dei progetti ICT Durante Iterazione 0 Il concetto di 束Just Enough損 per lIterazione 0 potrebbe includere: - Documenti architetturali di alto livello (ad es con UML) - Business Process diagram ad alto livello (ad es con BPMN o UML Activity Diagram) - Digrammi logici dei dati di alto livello - Template di 束Look and Feel損 - Tutto lo stretto necessario 90
- 91. Lo stato dell'arte sulla documentazione dei progetti ICT Modelli di interfaccia 91
- 92. Lo stato dell'arte sulla documentazione dei progetti ICT Documentare nel mondo Agile Nessuna rigida guideline su come documentare Focus : fornire valore al cliente Ripensare modo di documentare (vedremo nellesempio) Adattarsi al cambiamento Documentare dove quanto e come necessario 92
- 93. Lo stato dell'arte sulla documentazione dei progetti ICT Collaborative software o groupware Sono software che hanno lo scopo di facilitare e rendere efficace il lavoro cooperativo di un gruppo di persone. Il termine "Groupware" fu coniato nel 1978 da Peter e Trudy Johnson-Lenz. Gli autori intendevano indicare con esso non solo il software, cio竪 il supporto informatico, che consente lo svolgimento di un lavoro di tipo collaborativo, ma anche i processi che ne regolano lo svolgimento. https://en.wikipedia.org/wiki/List_of_collaborative_software 93
- 94. Lo stato dell'arte sulla documentazione dei progetti ICT Confluence https://www.atlassian.com/software/confluence 94 Project Collaboration Knowledge Base Team documentation
- 95. Lo stato dell'arte sulla documentazione dei progetti ICT Agenda La documentazione nei progetti ICT Documentare nel mondo Agile Esempio di approccio 95
- 96. Lo stato dell'arte sulla documentazione dei progetti ICT Cosa non fare 96
- 97. Lo stato dell'arte sulla documentazione dei progetti ICT Esempio di approccio Allinizio del processo di design ci sono le Storie. Una storia 竪 una breve descrizione di una funzionalit che porta un vantaggio allutente. 97 Button Una storia non 竪 aggiungere un bottone ma una funzionalit utile allutente Una storia descrive un processo non una cosa.
- 98. Lo stato dell'arte sulla documentazione dei progetti ICT Storie, Features, Epiche 98 Giovanni Puliti Mokabyte.it
- 99. Lo stato dell'arte sulla documentazione dei progetti ICT Metafora Lambiente in cui una storia si svolge. La metafora ci fornisce un gruppo di astrazioni che possiamo modellare nel codice. 99 Metafora del Sistema
- 100. Lo stato dell'arte sulla documentazione dei progetti ICT Esempio di approccio 100 Epica (T > 2-3 settimane)
- 101. Lo stato dell'arte sulla documentazione dei progetti ICT Storia Il miglior modo di rappresentare una storia 101
- 102. Lo stato dell'arte sulla documentazione dei progetti ICT Storia 102 Mike Cohn's template
- 103. Lo stato dell'arte sulla documentazione dei progetti ICT Rivista on line 103 Lettori Moderatori / Editori Scrittori Articoli
- 104. Lo stato dell'arte sulla documentazione dei progetti ICT Story Map E una griglia in cui mettiamo tutte le nostre storie 104 Non me ne occupo ora Pochi dettagli
- 105. Lo stato dell'arte sulla documentazione dei progetti ICT Story Map 105 Ogni storia parte da un embrione e poi viene analizzata in dettaglio fino a quando 竪 approvata
- 106. Lo stato dell'arte sulla documentazione dei progetti ICT Story Map 106 Set Minimo di Storie per avere un sistema funzionante
- 107. Lo stato dell'arte sulla documentazione dei progetti ICT Use Case Diagram I casi duso vanno descritti sotto forma di scenario di interazione (dialogo) tra gli attori e il sistema. Lattenzione va rivolta allinterazione con gli attori, non a quali parti interne del sistema vengono coinvolte. 107
- 108. Lo stato dell'arte sulla documentazione dei progetti ICT Analisi funzionale e casi duso 108
- 109. Lo stato dell'arte sulla documentazione dei progetti ICT User Story Diagram (Use Case Diagram) 109 Ruoli (Attori in UML) 1) As a moderator I need to create a magazine to do something 2) As an author I need to create an article Per fare un articolo mi serve un magazine che lo contenga Dipendenza
- 110. Lo stato dell'arte sulla documentazione dei progetti ICT User Story Diagram (Use Case Diagram) Stereotype 110
- 111. Lo stato dell'arte sulla documentazione dei progetti ICT Epiche 111 Epica
- 112. Lo stato dell'arte sulla documentazione dei progetti ICT Inizio Da dove si inizia a implementare? Dalla storia con meno dipendenze entranti ! E la prima del 束set minimo per avere sistema funzionante損 Ora vediamo cosa fare per documentare come implementare la storia 112
- 113. Lo stato dell'arte sulla documentazione dei progetti ICT Activity Diagrams Mostrano le attivit che fanno parte di una o pi湛 storie. Utili se dobbiamo discutere o mostrare a stakeholder gli step necessari allimplementazione. A volte sostituibili da un elenco puntato nel documento di specifica o nella feature. 113
- 114. Lo stato dell'arte sulla documentazione dei progetti ICT Activity Diagram Vediamo il processo di approvazione di un commento 114 Start Non specifico i ruoli (chi fa cosa)
- 115. Lo stato dell'arte sulla documentazione dei progetti ICT Activity Diagram Laggiunta del commento al thread non 竪 visibile allutente 115 Comment Lapprovatore viene notificato via email ("mondo esterno")
- 116. Lo stato dell'arte sulla documentazione dei progetti ICT Guardie 116
- 117. Lo stato dell'arte sulla documentazione dei progetti ICT Merge 117
- 118. Lo stato dell'arte sulla documentazione dei progetti ICT 118 End
- 119. Lo stato dell'arte sulla documentazione dei progetti ICT Meno formale (lavagna) Tolgo Split e Merge e metto le frecce che escono direttamente da activity 119
- 120. Lo stato dell'arte sulla documentazione dei progetti ICT Use Case Diagram Servono come : specifica per la validazione da parte di committenti e stakeholders input alla progettazione del software bozza per il futuro manuale utente input per i test di accettazione 120
- 121. Lo stato dell'arte sulla documentazione dei progetti ICT Visualizzare il flusso dei messaggi Sappiamo cosa fare, ora vediamo come, usando un paio di interaction diagrams, che mostrano le interazione degli oggetti a runtime. 121
- 122. Lo stato dell'arte sulla documentazione dei progetti ICT Collaboration Diagram Mostrano gli oggetti (non le classi) a runtime e i messaggi che si scambiano per interagire. 122 Sincrono
- 123. Lo stato dell'arte sulla documentazione dei progetti ICT Posso rappresentare anche istanze di oggetti (classe Magazine) 123 Istanza MoltiQui la notazione delle frecce non 竪 come standard UML Output Decimale Uso decimali anche se aggiungo dopo e non voglio rinumerare tutto
- 124. Lo stato dell'arte sulla documentazione dei progetti ICT 124 User Lutente clicca in qualche GUI per approvare -> Azione asincrona che rappresento con mezza freccia (come UML 1)
- 125. Lo stato dell'arte sulla documentazione dei progetti ICT Timeout o non approvazioni 125
- 126. Lo stato dell'arte sulla documentazione dei progetti ICT Sequence Diagram Si possono vedere le stesse cose di un collaboration diagram, ma visivamente appaiono in modo molto diverso e permettono 束prospettive損 differenti e sono pi湛 semplici da leggere. 126
- 127. Lo stato dell'arte sulla documentazione dei progetti ICT Attivazione di un oggetto 127 Activation
- 128. Lo stato dell'arte sulla documentazione dei progetti ICT Sequence Diagram completo 128
- 129. Lo stato dell'arte sulla documentazione dei progetti ICT Relazioni tra classi CRC Cards Disegnare le relazioni tra classi dopo la rappresentazione dei messaggi 竪 pi湛 semplice, so cosa devo implementare e le dipendenze sono ovvie (no messaggi -> no relazioni). Nel diagramma mostro solo le relazioni usate ! 129
- 130. Lo stato dell'arte sulla documentazione dei progetti ICT CRC - Class Responsibility Collaborator 130 CRC Cards (occhio a Single Responsibility ) Responsibility Class Comment non contiene puntatore a Magazine (es. argomento di metodo) -> cambio colore
- 131. Lo stato dell'arte sulla documentazione dei progetti ICT Un po pi湛 formale UML Class relationship diagram 131 Alcuni oggetti di tipo Magazine avranno il ruolo di library in qualche collaboration diagram (ricordate?). I nomi alla fine della freccia indicano nomi di oggetti.
- 132. Lo stato dell'arte sulla documentazione dei progetti ICT Dal Class Diagram al codice 132
- 133. Lo stato dell'arte sulla documentazione dei progetti ICT Composition 133 Stereotype
- 134. Lo stato dell'arte sulla documentazione dei progetti ICT Qualified Associations 134 Un Magazine contiene un dizionario con pi湛 articoli di diversi autori (Persone)
- 135. Lo stato dell'arte sulla documentazione dei progetti ICT Magazine 135 Un metodo per ogni freccia entrante in Magazine nel Collaboration Diagram
- 136. Lo stato dell'arte sulla documentazione dei progetti ICT Un articolo contiene molti commenti (la propriet la chiamo all) 136
- 137. Lo stato dell'arte sulla documentazione dei progetti ICT Subset I pending comments sono un sottoinsieme di all. Aggregation indica che quando Article viene distrutto i pending comments e gli author esistono ancora 137 Aggregation
- 138. Lo stato dell'arte sulla documentazione dei progetti ICT Article 138
- 139. Lo stato dell'arte sulla documentazione dei progetti ICT Comment 139
- 140. Lo stato dell'arte sulla documentazione dei progetti ICT Propriet Aggiungo delle property a Person 140
- 141. Lo stato dell'arte sulla documentazione dei progetti ICT Inheritance Il nostro sito contiene Post, che sono articoli e discussioni. Li posso rappresentare in due modi. 141 Ball and Socket notation
- 142. Lo stato dell'arte sulla documentazione dei progetti ICT State Diagram Utili quando comportamento cambia in base allo stato. Es: Nella classe Blog il metodo display() di un commento fa cose diverse, a seconda che il commento sia pending, approved o archived. 142
- 143. Lo stato dell'arte sulla documentazione dei progetti ICT State Diagram di un commento 143 Start Qualcuno sta scrivendo User ha premuto Submit Commento diventa pending
- 144. Lo stato dell'arte sulla documentazione dei progetti ICT Gli altri diagrammi UML ? Deplyoment Diagrams Component Diagrams Activity realization diagrams Package diagrams Subsystem Diagrams Utili ? A chi implementa non sempre, dipende dai casi. A volte servono solo per documentazione. 144
- 145. Lo stato dell'arte sulla documentazione dei progetti ICT Agile Analysis Template http://www.fernandomadeira.me/#free-resources Template che aiuta a: - organizzare i bisogni del cliente (Needs) - scoprire visione del business e lobiettivo della soluzione (Scope) - Assegnare priorit ai requisiti (Prioritizing) - Organizzare i rilasci seco un piano (Roadmap) secondo il concetto di Minimum Viable Product 145
- 146. Lo stato dell'arte sulla documentazione dei progetti ICT Risorse 146
- 147. Lo stato dell'arte sulla documentazione dei progetti ICT 147 Fine Sta a te decidere se leggerlo in inglese, oppure in italiano
- 148. Lo stato dell'arte sulla documentazione dei progetti ICT 148