Documentation-Examples-182x182Large corporate regulated environments such as banks and pharmaceuticals require documentation to fulfill a number of requirements.

As Scrum provides no guidance on documentation we will map typical documents onto DSDM Atern Products. We’ll be looking at what is necessary and what is not and at which point it gets covered by the DSDM Atern Lifecycle.

 

We will be looking at documents that are created:

  • Just once
  • Periodically
  • For each release, for Internal or External use
  • Only if needed
  • Not really needed

Simply click on each tab and click on the images to enlarge it.

Documentation-Figure-1

  • Detailed Business Case
  • Testing Strategy
  • Before & After High-Level Architecture

For a new product or a project, these are artefacts that will be produced just once, albeit to a high standard. Why? Because they contain information that is valid for the entire project lifecycle and will be read and referred to by many individuals. Of course there may be updates but the critical deciding factors are a long life with many readers.  

et-infoWriting a Test Strategy is good practice as project teams will need to know what is expected of them before they enter the time-boxes. They do not want to find out at the end of the timebox or worse in the middle of the project that extra testing requirements are needed.
Documentation-Figure-2

  • Detailed Business Case
  • Testing Strategy
  • Before & After High-Level Architecture

For a new product or a project, these are artefacts that will be produced just once, albeit to a high standard. Why? Because they contain information that is valid for the entire project lifecycle and will be read and referred to by many individuals. Of course there may be updates but the critical deciding factors are a long life with many readers.  

et-infoRe-use burn-down charts and employ RAG to report monthly status. Agree the monthly status with the Sponsor, Visionary, Architect and Team Leaders to report as one “voice”.

Documentation-Figure-3

  • User Guide
  • Installation & Upgrade Guides
  • Release Notes
  • Operating Guides

These need to be updated constantly. We do not want to be updating them at the end of the project, or worse after it. It is better to work on these in the same timebox as the software is produced.

They will need to be delivered early as part of Alpha or Beta releases for testing purposes. e.g. Operators will want to test overnight jobs before go-live and will certainly want to test upgrade scripts before the real cut-over to the new system. In other words, whenever the software is delivered, these artefacts need to be made available.

Depending on whether or not the users are internal or external you will need to choose the format wisely. Wiki systems are often ideal yet access will be required by external users if there is a vendor / client relationship, especially one with many clients.

et-infoMaintaining user-guides is actually very intensive. It may be better to provide a series of videos. They are quick to produce and reflect actual use.

Documentation-Figure-4

  • Test Data
  • Test Cases
  • Test Automation (Unit & Business)
  • Test Results

With the rise in popularity of Test Driven Development and Acceptance Test Driven Development, these artefacts are created at the same time as the software, in time-boxes. These artefacts are used often and for the entire duration of the project. With continuous integration practices and automation of tests, the results can be recorded as videos and actually used for internal training purposes as well evidence of a working product.

et-info

In some environments developers may be reluctant to think of test artefacts as part of their responsibility or worse as part of the product. It makes far more sense for these artefacts to be considered as important if not more important than the code. This is a strong sign of the maturity of the team.

Documentation-Figure-5

  • Screen & Report Layout Designs

A great deal of time can be spent detailing the use of every screen in a system and the layout of every report. Any documentation will be obsolete the moment the code is written. However, do consider such artefacts if they aid understanding. For example, if a new GUI is being designed, it will help to create a sample of screens that illustrate how the interaction will be experienced together with the look-and-feel of sample components.

et-infoWhen designing a new interface create a click-able mock-up or prototype and test it with a number of users before deciding the technical solution. If the technology is decided before the interaction, the solution may be limited which may be a decision that needs to be lived with for many years.

  • Detailed Requirements
  • Detailed Specifications
  • Detailed Designs

These all prescribe something that does not yet exist. They are therefore, vulnerable to change and should be avoided.

et-infoWhen Agile teams are working well together, they will do the detailed analysis and design as a team at the start of each timebox. They need to do this in order to commit to the scope of the Timebox. If they cannot commit, the team will highlight what is at risk. If this is perceived to be violating the high-level scope, the Delivery Plan will need to be updated (but at least the project know this weeks if not months ahead of delivery).

 

Documentation-Figure-1

  • Detailed Business Case
  • Testing Strategy
  • Before & After High-Level Architecture

For a new product or a project, these are artefacts that will be produced just once, albeit to a high standard. Why? Because they contain information that is valid for the entire project lifecycle and will be read and referred to by many individuals. Of course there may be updates but the critical deciding factors are a long life with many readers.

 

et-infoWriting a Test Strategy is good practice as project teams will need to know what is expected of them before they enter the time-boxes. They do not want to find out at the end of the timebox or worse in the middle of the project that extra testing requirements are needed.

Documentation-Figure-2

  • Detailed Business Case
  • Testing Strategy
  • Before & After High-Level Architecture

For a new product or a project, these are artefacts that will be produced just once, albeit to a high standard. Why? Because they contain information that is valid for the entire project lifecycle and will be read and referred to by many individuals. Of course there may be updates but the critical deciding factors are a long life with many readers.

 

et-infoRe-use burn-down charts and employ RAG to report monthly status. Agree the monthly status with the Sponsor, Visionary, Architect and Team Leaders to report as one “voice”.

Documentation-Figure-3

  • User Guide
  • Installation & Upgrade Guides
  • Release Notes
  • Operating Guides

These need to be updated constantly. We do not want to be updating them at the end of the project, or worse after it. It is better to work on these in the same timebox as the software is produced.

They will need to be delivered early as part of Alpha or Beta releases for testing purposes. e.g. Operators will want to test overnight jobs before go-live and will certainly want to test upgrade scripts before the real cut-over to the new system. In other words, whenever the software is delivered, these artefacts need to be made available.

Depending on whether or not the users are internal or external you will need to choose the format wisely. Wiki systems are often ideal yet access will be required by external users if there is a vendor / client relationship, especially one with many clients.

et-infoMaintaining user-guides is actually very intensive. It may be better to provide a series of videos. They are quick to produce and reflect actual use.

Documentation-Figure-4

  • Test Data
  • Test Cases
  • Test Automation (Unit & Business)
  • Test Results

With the rise in popularity of Test Driven Development and Acceptance Test Driven Development, these artefacts are created at the same time as the software, in time-boxes. These artefacts are used often and for the entire duration of the project. With continuous integration practices and automation of tests, the results can be recorded as videos and actually used for internal training purposes as well evidence of a working product.

et-info

In some environments developers may be reluctant to think of test artefacts as part of their responsibility or worse as part of the product. It makes far more sense for these artefacts to be considered as important if not more important than the code. This is a strong sign of the maturity of the team.

Documentation-Figure-5

  • Screen & Report Layout Designs

A great deal of time can be spent detailing the use of every screen in a system and the layout of every report. Any documentation will be obsolete the moment the code is written. However, do consider such artefacts if they aid understanding. For example, if a new GUI is being designed, it will help to create a sample of screens that illustrate how the interaction will be experienced together with the look-and-feel of sample components.

et-infoWhen designing a new interface create a click-able mock-up or prototype and test it with a number of users before deciding the technical solution. If the technology is decided before the interaction, the solution may be limited which may be a decision that needs to be lived with for many years.

  • Detailed Requirements
  • Detailed Specifications
  • Detailed Designs

These all prescribe something that does not yet exist. They are therefore, vulnerable to change and should be avoided.

et-infoWhen Agile teams are working well together, they will do the detailed analysis and design as a team at the start of each timebox. They need to do this in order to commit to the scope of the Timebox. If they cannot commit, the team will highlight what is at risk. If this is perceived to be violating the high-level scope, the Delivery Plan will need to be updated (but at least the project know this weeks if not months ahead of delivery).