1. 1 Chapter 6 Artifacts of the Process Materials taken directly from Walker Royce’s textbook.

2. 2 Introduction Know that most modern systems are composed of many components – some custom, some reused, some commercial – and many of these may operate in a variety of dissimilar networks on a variety of computing plateforms with different operating systems. Know that most modern systems are composed of many components – some custom, some reused, some commercial – and many of these may operate in a variety of dissimilar networks on a variety of computing plateforms with different operating systems. This different sources of these components dictates This different sources of these components dictates different methods in creating artifacts and, different methods in creating artifacts and, different approaches to traceability. different approaches to traceability.

3. 3 Artifact Development No longer sequential, complete. (Very difficult – especially – for senior mgmt to buy into in some cases… No longer sequential, complete. (Very difficult – especially – for senior mgmt to buy into in some cases… Now, artifacts are developed iteratively; evolve with development … together; Now, artifacts are developed iteratively; evolve with development … together; Different levels of abstractions …. Different levels of abstractions …. Artifacts evolve together in balanced granularity Artifacts evolve together in balanced granularity Exactly what the evolutions are - are choices and affect how requirements, design, etc. proceed… Exactly what the evolutions are - are choices and affect how requirements, design, etc. proceed… Activities necessitate repeatedly upgrading and ‘enriching’ these artifacts as our knowledge increases. Activities necessitate repeatedly upgrading and ‘enriching’ these artifacts as our knowledge increases. Models are continually refined, improved, enhanced…. Models are continually refined, improved, enhanced….

4. 4 6.1 The Artifact Sets Artifacts are organized into two sets Artifacts are organized into two sets Management set Management set Planning artifacts and Operational artifacts Planning artifacts and Operational artifacts Engineering set – all have different qualities and representations Engineering set – all have different qualities and representations Requirements setDesign set Requirements setDesign set Implementation setDeployment set. Implementation setDeployment set. A set represents a complete aspect of the system. A set represents a complete aspect of the system. An artifact represents some cohesive information typically developed and reviewed as a single entity An artifact represents some cohesive information typically developed and reviewed as a single entity e.g. prototype, or Use Case model, design model e.g. prototype, or Use Case model, design model

5. 5 Management Set Mainly captured in text perhaps some graphics. Mainly captured in text perhaps some graphics. These artifacts are mainly designed to capture data associated with process planning and execution. These artifacts are mainly designed to capture data associated with process planning and execution. Text and graphics will include whatever is necessary to capture the contracts among the project personnel, among stakeholders, and between project personnel and stakeholders. Text and graphics will include whatever is necessary to capture the contracts among the project personnel, among stakeholders, and between project personnel and stakeholders.

6. 6 Specific Artifacts in the Management Set Work Breakdown Structure - Activity breakdown and financial Work Breakdown Structure - Activity breakdown and financial tracking mechanisms tracking mechanisms Business Case - Cost, schedule, profit expectations Business Case - Cost, schedule, profit expectations Release Specifications - Scope, plan, objectives for release baselines Release Specifications - Scope, plan, objectives for release baselines Software Development Plan - Project process instance Software Development Plan - Project process instance Release Descriptions - Results of release baselines Release Descriptions - Results of release baselines Status Assessments - Periodic snapshots of project progress Status Assessments - Periodic snapshots of project progress Software Change Orders - Descriptions of discrete baseline changes Software Change Orders - Descriptions of discrete baseline changes Deployment documents - Cutover plan, training course Deployment documents - Cutover plan, training course Environment - Hardware and software tools, process automation, Environment - Hardware and software tools, process automation, documentation, training, production of engineering artifacts (documents, manuals, …) documentation, training, production of engineering artifacts (documents, manuals, …) ALL ARE VERY IMPORTANT IN THE MANAGEMENT SET!

7. 7 Specific Artifacts in the Management Set Evaluated, assessed and measured primarily via Evaluated, assessed and measured primarily via Reviews with relevant stakeholder Reviews with relevant stakeholder Analysis of changes between current version of artifact and previous versions Analysis of changes between current version of artifact and previous versions Milestone demonstrations of the balance among the artifacts, and the accuracy of the business case and vision artifacts (cost, schedule, profit expectations, quality, progress…) Milestone demonstrations of the balance among the artifacts, and the accuracy of the business case and vision artifacts (cost, schedule, profit expectations, quality, progress…)

8. 8 Engineering Set Unlike the Management Set, Unlike the Management Set, where we evaluate via stakeholder review, comparing current with previous versions, progress between artifacts (delivered and planned), where we evaluate via stakeholder review, comparing current with previous versions, progress between artifacts (delivered and planned), In the Engineering Set, the primary mechanism for evaluating the evolving quality of these artifact sets is in the transitioning of information from set to set (requirements to design to …) In the Engineering Set, the primary mechanism for evaluating the evolving quality of these artifact sets is in the transitioning of information from set to set (requirements to design to …) thereby maintaining a balance of understanding among the artifacts in these sets. Each of these evolve over time! Each of these evolve over time!

9. 9 Engineering Set – Requirements Set Vision Statement – Notation: normally text. Vision Statement – Notation: normally text. Documents project scope that supports the contract between the funding authority and the project team. Documents project scope that supports the contract between the funding authority and the project team. Supplementary Specs – variety of formats Supplementary Specs – variety of formats Can come from regulatory agencies, other prototypes indicating proof of concept. Can come from regulatory agencies, other prototypes indicating proof of concept. Requirements models - Notation usually captured in UML Requirements models - Notation usually captured in UML Use Case modeling and domain modeling; activity diagrams. Use Case modeling and domain modeling; activity diagrams. “  The requirements set is the primary engineering context for evaluating the other three engineering artifact sets and is the basis for test cases.” (p.86) “  The requirements set is the primary engineering context for evaluating the other three engineering artifact sets and is the basis for test cases.” (p.86)

10. 10 Engineering Set – Requirements Set Evaluation, Assessment, and Measurement? (main…) Evaluation, Assessment, and Measurement? (main…)  Evaluate the consistency between vision and requirements models; (What are requirements models?)  Evaluate the consistency between vision and requirements models; (What are requirements models?) Mappings against the design, implementation, and deployment sets to evaluate the consistency and completeness and semantic balance between the information in different sets. Mappings against the design, implementation, and deployment sets to evaluate the consistency and completeness and semantic balance between the information in different sets. Meaning? Discuss…- … level of granularity… Meaning? Discuss…- … level of granularity… Analysis of change between current versions of requirements artifacts and previous versions. Analysis of change between current versions of requirements artifacts and previous versions. How much scrap/rework are really needed? How much scrap/rework are really needed? Overall subjective review of other factors…. Overall subjective review of other factors….

11. 11 Engineering Set – Design Set Notation: UML; Tools used: visually modeling tools. Notation: UML; Tools used: visually modeling tools. Contains levels of abstraction: components in the solution space. Contains levels of abstraction: components in the solution space. Identities, static relationships, dynamic interactions Identities, static relationships, dynamic interactions Class diagrams, interaction diagrams, state charts, relationships… Class diagrams, interaction diagrams, state charts, relationships… Can, in some cases, be automatically translated into a subset of the implementation and deployment set artifacts. (Discuss) Can, in some cases, be automatically translated into a subset of the implementation and deployment set artifacts. (Discuss) Design set artifacts normally include: design model, test model, software architecture description (part of design model). Design set artifacts normally include: design model, test model, software architecture description (part of design model). Some authors: preliminary design (architectural components; static relationships…) and detail design (more detailed dynamic interactions ) Some authors: preliminary design (architectural components; static relationships…) and detail design (more detailed dynamic interactions )

12. 12 Engineering Set – Implementation Set Tools used in Implementation: debuggers, compilers, code analyzers, test coverage analysis tools, test management tools… Tools used in Implementation: debuggers, compilers, code analyzers, test coverage analysis tools, test management tools… Implementation Set artifacts includes: source code (as implementation of components) their form, interfaces, and dependencies) and executables necessary for stand-alone testing of components. Implementation Set artifacts includes: source code (as implementation of components) their form, interfaces, and dependencies) and executables necessary for stand-alone testing of components. These executables are the primitive parts needed to construct the end products including custom components, APIs, other reusable or legacy components in some programming languages. These executables are the primitive parts needed to construct the end products including custom components, APIs, other reusable or legacy components in some programming languages.  Implementation sets are often packaged and form a subset of the deployment set.  Implementation sets are often packaged and form a subset of the deployment set.

13. 13 Engineering Set – Deployment Set Tools used in setting things up for / getting ready for deployment: test coverage and test automation tools; network management tools, commercial components (OS, GUI, DBMSs, middleware, installation tools, etc.) Tools used in setting things up for / getting ready for deployment: test coverage and test automation tools; network management tools, commercial components (OS, GUI, DBMSs, middleware, installation tools, etc.) Deployment set artifacts normally include the deliverables and machine language notations, executable software, build scripts, installation scripts, and executable target specific data necessary to use the product in its target environment. Deployment set artifacts normally include the deliverables and machine language notations, executable software, build scripts, installation scripts, and executable target specific data necessary to use the product in its target environment.

14. 14 Engineering Set – Deployment Set Test the partitioning, replication, and allocation strategies in mapping components of the implementation set to physical resources of the deployment system (platform type, number, network topology). (  test the loading, configuring, building…) Remember, you are often getting ready to send these thing out! Test the partitioning, replication, and allocation strategies in mapping components of the implementation set to physical resources of the deployment system (platform type, number, network topology). (  test the loading, configuring, building…) Remember, you are often getting ready to send these thing out! Tested against defined use scenarios in the user manual such as installation, user-oriented dynamic reconfiguration, mainstream usage, and anomaly management. Tested against defined use scenarios in the user manual such as installation, user-oriented dynamic reconfiguration, mainstream usage, and anomaly management. Analysis of changes between current version and previous version of deployment set (if appropriate). Analysis of changes between current version and previous version of deployment set (if appropriate). Subjective review of other quality dimensions… Subjective review of other quality dimensions…

15. 15 Comments on Sets Each artifact set uses different notations appropriate to its focus. Each artifact set uses different notations appropriate to its focus. Management Set uses text, graphics, Use Cases… to capture of plans, progress, acceptance criteria, and other management docs. Management Set uses text, graphics, Use Cases… to capture of plans, progress, acceptance criteria, and other management docs. Requirement notations (in Engineering Set) uses (structured text and UML models) to capture engineering context and the operational concept. (Structured English, Use Case Diagrams, Activity Diagrams) (problem space artifacts, if you will…) Requirement notations (in Engineering Set) uses (structured text and UML models) to capture engineering context and the operational concept. (Structured English, Use Case Diagrams, Activity Diagrams) (problem space artifacts, if you will…) Design notations (use UML) capture engineering blueprints (architectural design, component design). (class, Use Case realization artifacts (sequence diagrams, collaboration diagrams, state diagrams…) (solutions space) Design notations (use UML) capture engineering blueprints (architectural design, component design). (class, Use Case realization artifacts (sequence diagrams, collaboration diagrams, state diagrams…) (solutions space) Implementation notations (software languages …) capture building blocks in solution space in human-readable form (source code, dll, exe., test scripts, test plans, test data, results. Implementation notations (software languages …) capture building blocks in solution space in human-readable form (source code, dll, exe., test scripts, test plans, test data, results. Deployment notations: (executable artifacts and data files) – capture solution in machine-readable formats. What is sent to the customer or installed for the customer…. Deployment notations: (executable artifacts and data files) – capture solution in machine-readable formats. What is sent to the customer or installed for the customer….

16. 16 Artifact Set Focus: Requirement sets – covered mainly in Inception Requirement sets – covered mainly in Inception Design artifact sets – mainly in elaboration Design artifact sets – mainly in elaboration Implementation sets – construction Implementation sets – construction Deployment sets – transition Deployment sets – transition But not EXCLUSIVELY in these phases!!! But not EXCLUSIVELY in these phases!!! Requirements receive a lot of treatment in Elaboration; Some Design precedes and follows Elaboration; What? Some Implementation will take place in Transition; What? and Some preparation for Deployment sets will take place Requirements receive a lot of treatment in Elaboration; Some Design precedes and follows Elaboration; What? Some Implementation will take place in Transition; What? and Some preparation for Deployment sets will take place during Construction. What? Do you understand what? during Construction. What? Do you understand what? Good, and important questions. Study these.

17. 17 Implementation Set versus Deployment Set Artifacts (1 of 3) Several similarities and significant differences! Several similarities and significant differences! Generalizing: Implementation set – source code; deployment set – executable code. Generalizing: Implementation set – source code; deployment set – executable code. Sounds similar, but there are several very different concerns associated with these… Sounds similar, but there are several very different concerns associated with these… Remember, in Implementation, we are coding (source code) and performing unit testing (and more…) Remember, in Implementation, we are coding (source code) and performing unit testing (and more…) Almost all these activities are included in Construction Almost all these activities are included in Construction In Deployment, the organization of ‘code’ presented to the user and sometimes the test organization in customer’s shop is vastly different from the source code information characterizing the implementation set. In Deployment, the organization of ‘code’ presented to the user and sometimes the test organization in customer’s shop is vastly different from the source code information characterizing the implementation set.

18. 18 Implementation Set versus Deployment Set 2 of 3 In the deployment set, we are concerned with providing artifacts that support loading, installation, configuration, testing, and operations. So, we are concerned with: (directly from text – for discussion…) In the deployment set, we are concerned with providing artifacts that support loading, installation, configuration, testing, and operations. So, we are concerned with: (directly from text – for discussion…) Dynamically reconfigurable parameters – Meaning? Dynamically reconfigurable parameters – Meaning? Buffer sizes, color palettes, number of servers, number of simultaneous clients, data files, run-time parameters…) Buffer sizes, color palettes, number of servers, number of simultaneous clients, data files, run-time parameters…) Effects of compile/link optimizations (space versus speed optimizations) – Meaning? Effects of compile/link optimizations (space versus speed optimizations) – Meaning? Performance under certain allocation strategies – Meaning? Performance under certain allocation strategies – Meaning? Centralized versus distributed; primary vs shadow threads, dynamic load balancing, hot backup vs checkpoint/rollback Centralized versus distributed; primary vs shadow threads, dynamic load balancing, hot backup vs checkpoint/rollback Virtual machine constraints (file descriptors, garbage collection, heap size, speed of disks, …) Virtual machine constraints (file descriptors, garbage collection, heap size, speed of disks, …) Process-level concurrency issues (deadlock and race conditions) Process-level concurrency issues (deadlock and race conditions) Know what deadlock and races are? Meaning? Know what deadlock and races are? Meaning? Platform specific differences in performance or behavior Platform specific differences in performance or behavior

19. 19 Implementation Set versus Deployment Set 3 of 3 All kinds of installation and configuration info must be passed into operational environment either All kinds of installation and configuration info must be passed into operational environment either Via implementation set (embedded in source code…) or Via implementation set (embedded in source code…) or Via deployment set (embedded in data files, configuration files, installation scripts, …) Via deployment set (embedded in data files, configuration files, installation scripts, …) Example: try ‘blocking factor….’ Example: try ‘blocking factor….’ Deployment of commercial products to customers can span a broad range of test and deployment configurations. Deployment of commercial products to customers can span a broad range of test and deployment configurations.

20. 20  Artifact Evolution over Life Cycle 1 of 2 Unlike the conventional approach, phases (requirements, design, etc.) are NOT complete before proceeding to next phase.  (Cite NFRUG’s meeting discussion.) Unlike the conventional approach, phases (requirements, design, etc.) are NOT complete before proceeding to next phase.  (Cite NFRUG’s meeting discussion.) The entire system evolves as the ‘state of the system evolves into more elaborate states.’ The entire system evolves as the ‘state of the system evolves into more elaborate states.’ With this, the artifact sets evolve accordingly. With this, the artifact sets evolve accordingly. Each phase (inception, elaboration, construction, transition) realizes some degree of effort (more evolution) on all artifact sets plus the management set. Each phase (inception, elaboration, construction, transition) realizes some degree of effort (more evolution) on all artifact sets plus the management set. Clearly, some phases emphasize one artifact set over others… Clearly, some phases emphasize one artifact set over others…

21. 21 Artifact Evolution over Life Cycle 2 of 2 “During the transition phase, traceability between the requirements set and the deployment set is extremely important. “During the transition phase, traceability between the requirements set and the deployment set is extremely important. The evolving requirements set captures a mature and precise representation of the stakeholders’ acceptance criteria, and (what does this sentence MEAN to you?) The evolving requirements set captures a mature and precise representation of the stakeholders’ acceptance criteria, and (what does this sentence MEAN to you?) the deployment set represents the actual end-user product. the deployment set represents the actual end-user product. “Therefore, during the transition phase, completeness and consistency between these two sets are important. “Therefore, during the transition phase, completeness and consistency between these two sets are important. “Traceability among the other sets is necessary only to the extent that it aids the engineering (development) or management activities.” p. 93 “Traceability among the other sets is necessary only to the extent that it aids the engineering (development) or management activities.” p. 93

22. 22 Test Artifacts (1 of 2) In Conventional development, a number of test documents were created. In Conventional development, a number of test documents were created. Very difficult to keep them all consistent Very difficult to keep them all consistent Test documents for everything: Test documents for everything: Unit test, integrated testing, test plans, test procedures… Unit test, integrated testing, test plans, test procedures… Different formats; levels of granularity, … Different formats; levels of granularity, … In our process, we use the same artifact sets and notations that were used for product development for the test activities In our process, we use the same artifact sets and notations that were used for product development for the test activities

23. 23 Test Artifacts (2 of 2)  We include testing information in all development artifacts.  We include testing information in all development artifacts.  Test artifacts are developed concurrently with product from inception through development.  Test artifacts are developed concurrently with product from inception through development. Testing is a full life-cycle activity – NOT a late life-cycle activity as it used to be in Conventional software development. Testing is a full life-cycle activity – NOT a late life-cycle activity as it used to be in Conventional software development. Test artifacts are included in same artifacts as the developed products. Test artifacts are included in same artifacts as the developed products. Test artifacts are thus documented in the same way that the product is documented Test artifacts are thus documented in the same way that the product is documented Developers of the test artifacts use the same tools, techniques, and training as the software engineers developing the product. Developers of the test artifacts use the same tools, techniques, and training as the software engineers developing the product.

24. 24 6.2 Management Artifacts Many artifacts that document the product, the process, improvement actions, and management of the process in general. Many artifacts that document the product, the process, improvement actions, and management of the process in general. “Document” does not necessarily mean ‘paper,’ as so much nowadays is done via electronic means (discussed ahead). “Document” does not necessarily mean ‘paper,’ as so much nowadays is done via electronic means (discussed ahead). You need to be aware of some of these basic concepts/emphases of management artifacts that follow, as they leave an audit trail of our efforts. You need to be aware of some of these basic concepts/emphases of management artifacts that follow, as they leave an audit trail of our efforts.

25. 25 Management Artifacts Work Breakdown Structure (WBS) WBS is a VERY commonly used ‘document’ WBS is a VERY commonly used ‘document’ Absolutely essential for Management!! Absolutely essential for Management!! Essential for tracking expenses throughout development – all phases and activities. Essential for tracking expenses throughout development – all phases and activities. Basically it focuses on budgeting, monitoring, and controlling project costs. Basically it focuses on budgeting, monitoring, and controlling project costs. How resources are expended for activities undertaken How resources are expended for activities undertaken Trends and projections…. Trends and projections…. Checked at end of minor milestones (iterations) and definitely at major milestones (phase completions) Checked at end of minor milestones (iterations) and definitely at major milestones (phase completions)

26. 26 Management Artifacts Business Case Essential! Provides info to decide whether or not project is worth investing in. Pure Economics! Essential! Provides info to decide whether or not project is worth investing in. Pure Economics! Includes expected costs, expected revenues, technical and management plans, consideration of risk, expected ROI, etc. Includes expected costs, expected revenues, technical and management plans, consideration of risk, expected ROI, etc. Effects of NOT investing in project, etc. Effects of NOT investing in project, etc. Normally accommodated in text; graphics…. Normally accommodated in text; graphics…. Purpose: transform Vision document into economic terms. Purpose: transform Vision document into economic terms. A Global View of the Vision document is that it contains the requirements… (functional and non-functional) Customer views / expectations of the delivered, operational system. A Global View of the Vision document is that it contains the requirements… (functional and non-functional) Customer views / expectations of the delivered, operational system.

27. 27 Management Artifacts Release Specifications Documentation accompanying every release. Documentation accompanying every release. Derived from Vision statement, development, and testing. Derived from Vision statement, development, and testing. Artifacts constituting the Release Specs evolve and achieve finer granularity as development proceeds. Not written up at the ‘end!!’ Artifacts constituting the Release Specs evolve and achieve finer granularity as development proceeds. Not written up at the ‘end!!’ Two kinds of requirements info addressed in Release specifications: Two kinds of requirements info addressed in Release specifications: Vision Statement – evolutionary… High level requirements modeled here… Vision Statement – evolutionary… High level requirements modeled here… Recall: Vision statement serves as Contract between developers and customer Recall: Vision statement serves as Contract between developers and customer Vision usually contains the Use Case Model and Use Case Descriptions. (SRS) Vision usually contains the Use Case Model and Use Case Descriptions. (SRS) Evaluation criteria – details (often lower level) on how to evaluate… Evaluation criteria – details (often lower level) on how to evaluate…  Snapshots of objectives for a milestone achieved  Snapshots of objectives for a milestone achieved  How do we know / demonstrate that we achieved the objectives of the iteration??  How do we know / demonstrate that we achieved the objectives of the iteration?? Evaluation Criteria are defined as “Management Artifacts” vice Requirements Set. Evaluation Criteria are defined as “Management Artifacts” vice Requirements Set.  Evaluation Criteria are organized ‘by iteration,’  Evaluation Criteria are organized ‘by iteration,’  Need to be demonstrated…..  Need to be demonstrated…..  Traceability is essential  Traceability is essential Each iteration’s evaluation criteria may be discarded, once the milestone is complete. Each iteration’s evaluation criteria may be discarded, once the milestone is complete. Address high risk early and core functionalities… Address high risk early and core functionalities…

28. 28 Management Artifacts Software Development Plan (SDP) SDPs address development process in fine detail. SDPs address development process in fine detail. Sometimes called DPP, DPD, etc. Sometimes called DPP, DPD, etc.  Discusses required artifacts, who will do what, quality checkpoints, the development environment, configuration control board planning and procedures; change management, base-lining, assessment, risk and status assessment, standards to be adhered to, etc.  Discusses required artifacts, who will do what, quality checkpoints, the development environment, configuration control board planning and procedures; change management, base-lining, assessment, risk and status assessment, standards to be adhered to, etc. Covers whole spectrum of development activity. Covers whole spectrum of development activity.

29. 29 Management Artifacts Release Descriptions Release Descriptions document the contents of each release including performance against each of the evaluation criteria in the corresponding Release Spec. Release Descriptions document the contents of each release including performance against each of the evaluation criteria in the corresponding Release Spec. Release Descriptions have a Release Baseline that assert that the objectives of a release have been addressed and verified via: Release Descriptions have a Release Baseline that assert that the objectives of a release have been addressed and verified via: Demonstration, Demonstration, testing, testing, inspection, or inspection, or analysis analysis

30. 30 Management Artifacts Status Assessments  Essential for good project management  Essential for good project management  Snapshots of project health  Snapshots of project health Risk assessment Risk assessment Quality indicators Quality indicators Management indicators….what do you think? Management indicators….what do you think? Project proceeding according to expectations? Project proceeding according to expectations? “periodic heartbeat” of project. “periodic heartbeat” of project. A ‘HowGoesIt?” or “Weekly Activity Report” …. A ‘HowGoesIt?” or “Weekly Activity Report” …. Resource review, financial review, technical progress, action items and follow through…. Resource review, financial review, technical progress, action items and follow through…. Always done at end of minor and major milestones – and any other time management wishes, really… Always done at end of minor and major milestones – and any other time management wishes, really…

31. 31 Management Artifacts Software Change Order Database Essential! Essential! Now we have automation to assist in change management / control Now we have automation to assist in change management / control No more manual management/control! No more manual management/control! System Change Proposals (SCPs) …paper!!! System Change Proposals (SCPs) …paper!!! Have database to control, track, and manage change records (dates, priorities, …) – on line! Have database to control, track, and manage change records (dates, priorities, …) – on line! Reduces bureaucracy and supports metrics collection and reporting!!! Reduces bureaucracy and supports metrics collection and reporting!!!

32. 32 Management Artifacts Deployment For Large Contracts For Large Contracts Software may be delivered to a separate maintenance group; artifacts include operation manuals, software installation manuals, conversion plans, … for cutover. Software may be delivered to a separate maintenance group; artifacts include operation manuals, software installation manuals, conversion plans, … for cutover. For Small Contract; smaller corporation… For Small Contract; smaller corporation… Much MUCH less. Much MUCH less. Often same group of people do ALL! Often same group of people do ALL! Varies considerably from project to project. Varies considerably from project to project.

33. 33 Management Artifacts Environment Any first class development shop must have a robust, integrated suite of development tools to support the automation of the development process. Any first class development shop must have a robust, integrated suite of development tools to support the automation of the development process. Suite must include tools for: Suite must include tools for: Requirements management, Requirements management, Visual modeling, Visual modeling, Documentation automation, Documentation automation, Host/target programming tools, Host/target programming tools, Testing, Testing, Integrated change management, Integrated change management, Defect tracking… Defect tracking…

34. 34 Management Artifacts Recognize: Different activities generate different artifacts as part of minor milestones (ends of iterations) and major milestones (ends of phases). Different activities generate different artifacts as part of minor milestones (ends of iterations) and major milestones (ends of phases). Different artifacts are updated at different times and with different degrees of detail. Different artifacts are updated at different times and with different degrees of detail.  See figure on page 102.  See figure on page 102.

35. 35 Engineering Artifacts Three main documents (there are others…) Three main documents (there are others…) 1. Vision Document 1. Vision Document 2. Architecture Description 2. Architecture Description 3. User Manual 3. User Manual

36. 36 Engineering Artifacts Vision Document Complete vision for the software system under development and supports the contract between funding authority and development organization. Complete vision for the software system under development and supports the contract between funding authority and development organization. Can vary immensely in size. Can vary immensely in size. Meant to be changeable as understanding evolves – but should be slow… Meant to be changeable as understanding evolves – but should be slow… The vision document is written from the user’s perspective, focusing on the essential features the system is to provide and acceptable levels of quality. The vision document is written from the user’s perspective, focusing on the essential features the system is to provide and acceptable levels of quality. Contains Contains Use Cases and descriptions. Use Cases and descriptions. Risks inherent in the use case development and realization Risks inherent in the use case development and realization Operational capacities (volumes, response times, …) Operational capacities (volumes, response times, …) Interoperational interfaces with entities outside the system boundary. Interoperational interfaces with entities outside the system boundary. Should contain two appendices Should contain two appendices Operational Concept using use cases and Operational Concept using use cases and Risks inherent in the vision statement Risks inherent in the vision statement

37. 37 Engineering Artifacts Architecture Description Organized view of the software architecture under development Organized view of the software architecture under development Extracted from design level models and includes views of design, implementation, and deployment sets Extracted from design level models and includes views of design, implementation, and deployment sets (Think 4+1 architectural view…); (Think 4+1 architectural view…); Levels of granularity from design artifacts and their contents to architectural layers. Levels of granularity from design artifacts and their contents to architectural layers. Breadth will vary from project to project. Breadth will vary from project to project. Usually described using a subset of the design model or as an abstraction of the design model with supplementary material or combination of both… Usually described using a subset of the design model or as an abstraction of the design model with supplementary material or combination of both… Evolves just as any other artifact. Evolves just as any other artifact.

38. 38 Engineering Artifacts User Manual Reference document Reference document Content varies across application domains. Content varies across application domains. Must contain: Must contain: Installation procedures – how to install software; how to convert… Installation procedures – how to install software; how to convert… Usage procedures and guidance – How to use application Usage procedures and guidance – How to use application Operational constraints Operational constraints User Interface description – at a minimum. User Interface description – at a minimum. Should be written by members of the team. Should be written by members of the team. Can be written in parallel with development and evolve… Can be written in parallel with development and evolve… Provides the basis for  test plans and test cases! Provides the basis for  test plans and test cases! Ties back in with Vision Document (use cases) and prototype Ties back in with Vision Document (use cases) and prototype

39. 39 Pragmatic Artifacts Many years of many many documents!!!! Many years of many many documents!!!! Have often been impediments to progress… Have often been impediments to progress… The quality of the documents had become more important than information content. The quality of the documents had become more important than information content. Very lengthy and very detailed documents were perceived to indicate progress and resulted in premature engineering details and increased scrap and rework later… Very lengthy and very detailed documents were perceived to indicate progress and resulted in premature engineering details and increased scrap and rework later… In many cases level of detail did not reflect current understanding or decisions were made too early and rendered some information obsolete prior to the delivery of the application! In many cases level of detail did not reflect current understanding or decisions were made too early and rendered some information obsolete prior to the delivery of the application! Now - encourage on-line review of information by using smart browsing and navigation tools. Now - encourage on-line review of information by using smart browsing and navigation tools. Eliminates huge, unproductive sources of scrap later on. Eliminates huge, unproductive sources of scrap later on. Provides for continuous review, not periodic review…. Provides for continuous review, not periodic review….

40. 40 Pragmatic Artifacts Cultural Issues: Cultural Issues: 1. People want to review info but don’t understand the language of the artifact 1. People want to review info but don’t understand the language of the artifact …”provide a separate document/description?” No! …”provide a separate document/description?” No! Adds considerable time and cost w/o value Adds considerable time and cost w/o value 2. People want to review the info but don’t have access to the tools. 2. People want to review the info but don’t have access to the tools. Forced to produce paper? Forced to produce paper? Visualization tools, Web, and more are making artifacts readily accessible. Visualization tools, Web, and more are making artifacts readily accessible.

41. 41 Pragmatic Artifacts 3. Human-readable engineering artifacts should use rigorous notations that are complete, consistence and used in a self-documenting manner. 3. Human-readable engineering artifacts should use rigorous notations that are complete, consistence and used in a self-documenting manner. Good grammar; reading levels; professional editors… Good grammar; reading levels; professional editors… Avoid encrypting and abbreviations in documents and code. Avoid encrypting and abbreviations in documents and code. Make code self-documenting. Make code self-documenting. Software is written once; read and changed many times Software is written once; read and changed many times Emphasize readability and proper grammar! Emphasize readability and proper grammar! Anything else is … uncivilized! Anything else is … uncivilized!

42. 42 Pragmatic Artifacts 4. Useful documentation is self-defining. It is documentation that gets used. 4. Useful documentation is self-defining. It is documentation that gets used. Good documentation provides an engineer the opportunity to work alone!!! Good documentation provides an engineer the opportunity to work alone!!! Use notations that everyone uses and needs! Use notations that everyone uses and needs! Strive to be produce self-documenting artifacts!! Strive to be produce self-documenting artifacts!! ‘Documents’ can stand alone. ‘Documents’ can stand alone.

43. 43 Pragmatic Artifacts ‘Paper is tangible; artifacts are too easy to change.’ True, but… ‘Paper is tangible; artifacts are too easy to change.’ True, but… Comment lament by some stakeholders. Comment lament by some stakeholders. Skeptical due to volatility of on-line documentation. Skeptical due to volatility of on-line documentation. The whole world will eventually adopt this philosophy! The whole world will eventually adopt this philosophy! Most tools and environments will be developed to support change management, audit trails, electronic signatures, and other advances so that electronic interchange replaces paper! Most tools and environments will be developed to support change management, audit trails, electronic signatures, and other advances so that electronic interchange replaces paper! This is the 21 st century! This is the 21 st century!