What Documentation is Required on an Agile Project.

Two types of Documentation

          INDICATIVE Documentation

Documentation that is not part of the code should always be stamped or water marked as ‘INDICATIVE’.

INDICATIVE  documentation can be useful but be aware that it is then either ‘suspect bad’ or ‘useless’. This applies to photographs, retained yellow stickies and any other media that may be used.

          RELIABLE Documentation

Code written to identify the user and business rules used in the system is ‘RELIABLE’ documentation.

To get ‘RELIABLE’ documentation, it must be either

• part of the code (human friendly names etc, NOT annotation) or
• Part of the automatic testing, run when a new build is made.

 Use of Fitness for Regular Automatic Testing

Using a wiki based test tool likeFitNesse,

http://fitnesse.org/

allows wide distribution and support for the documentation, development and testing of the system.

Tests that pass are coloured green, whilst test that fail are coloured red, thus not just making the results of test easily seen, but also what tests passed or failed.

Concordian is another similar system, but I have not tried it.

http://concordion.org/

This is similar, with the distinct advantage, that tests can be written in advance of the code. When run, these tests are just highlighted in yellow implying that this has not yet been coded.

For both systems, classes are coded with a supporting test class, known as a ‘fixture’ that will allow the class to be tested automatically. The test data and results modify previously written wiki pages.

The wiki pages are normally built in an agreed  hierarchical  structure, allowing separation of the levels of testing in functional groupings, such as use cases.   They generally contain

• general text descriptions outlining the test  and
• tables of values that contain test data used by the automatic testing, including the expected results.

The text is INDICATIVE, but the tables are treated as part of the code and are RELIABLE.

When a new version of the system is built, the fixtures read the tables and compare the calculated result with the expected result. If they agree, the results cell in the table is coloured green. If they disagree, it is turned red. In Concordian, cells that have no fixtures are coloured yellow, where as in FitNesse they are failed with red.

The fixtures are very ‘techie’, and are the responsibility of the developers, but the nature of the tests are very human readable, and understandable by everyone from the business staff to the coders. Hence, anyone can modify the wiki text or tables. Business staff could start a new page, write some text describing some feature that they think should be tested.  They could also produce tables showing the test data that they think should be used. This can then be refined by analysts, tester and coders as they see more detail on what is needed.  Alternatively, a coder should create the page, and business staff, or testers, or analysts should modify the wiki bits. The project can switch between test first or code first approaches; developers will often spot tests that are needed but have been missed by the analysts. They just add them, in the spirit of agile, perhaps mentioning them at the next stand-up meeting. When the system has passed, the analysts will see the details of these extra tests in the wiki.

The whole world can see what has failed and why. Test may be spelled out at all levels;  the unit tests, system tests, user acceptance tests. Test switches may allow these tests to be run a few at a time. When the system is complete, all the tests should have been run, some as regression testing and some as new tests on new features.

The Proper Use of UML

Where I differ, from several other authors, is in analysing the requirements using UML. UML lets us clearly distinguish different types of tests. This extra level of analysis, not only helps everyone to visualise the system better, but it forces the tests into well defined categories that  need different types of testing. This division also identifies the level of these tests and when they are tested. It introduces  very little INDICATIVE documentation, but the control on the planned tests pays easily for that.

UML, used properly, allows the analysis of the requirements into distinctive types, which have distinctive patterns for testing. I emphasise the two words above, because I also disagree strongly with the recent trend, started by Alister Cockburn, whereby use cases become INDICATIVE mini specs and class diagrams are not part of the output. To overcome the huge size of these use cases, (I have seen some over 30 pages long, instead of the optimal 3 pages.), the actual requirements are listed in yet another INDICATIVE document called the Requirements Register.

UML breaks the analysis into two parts:

1. Use Cases -

These are of primary interest to the user community. Use cases should describe WHAT interfaces to the system exist and what their protocol is. It does NOT explain how the system processes them in any way.

To judge this, 90% of the steps in the scenario should be of the form of

• One statement ‘User does’
• One response ‘System does’

A few exceptions exist:

• These two are split by another pair
• System communicates with a secondary actor
• The secondary actor responds
• The system switches to an alternative path, which itself must not be more than 4 or 5 pairs of user/system interaction. If it is larger, then it should be made a secondary use case.
• The system response is to report a failure and head towards closure of the use case.
• An ‘exception’ close the use case immediately.

A typical use case has around 9 pairs  of statements in a scenario;  it can have more, but you should think carefully about it as you may be describing UI rules or business rules

Use Cases come in several flavours:

1.1. Primary use cases -

They are triggered by the user when they want to do

‘One Thing, at One Time, by One Person (Actor) in one Place’

OTOT-OPOP.

            1.2. Secondary Use Cases – support primary use cases

                    1.2a. <included> use cases. The goal of these is INCLUDED in the goal of the primary use case. They are distinguished for convenience, either to provide clarity to the user or for sharing code.

1.2b. <extended> use cases. The goal of these EXTENDS the goal of the primary use case.

Either of these can be shared and either can be optional. Confusion over what they are, arises because the greater majority of shared code is implemented as <included> use cases and the greater majortity of optional code is implemented as <extended> use cases. Using the definitions that gave them their name gives the correct definition.

Note: all user stories can be expressed as one of these types of use cases. “As an <actor> I wish to ‘do One Thing’ so that I create (or expand) some use case functionality.

Ok, after that use case is complete, it may be decided to make the secondary use case becomes  part of the primary use case. That is what agile is about. Agile also applies to the analysis, and NOT just the code.

With this level of simplicity, the whole of the use case can be added to Fitnesse.

• Is the actor appropriate?
• Are the pre-conditions met?
• Are the correct triggers available?
• Do the steps follow in the correct order?
• Was the Goal, expressed as the post conditions, attained as expected.

So only the introductory use case diagrams are INDICATIVE. The whole use case has been encapsulated in a RELIABLE automatic test suite. Yet this significant test is very easily understood from the very visual wiki pages. Each of the above will be displayed as onr or may be two tables, which ‘blush’ appropriately.

The business rules have already been rigorously tested, and so only one or two of them are tested, just to confirm that such things still work in the use case.

          2. Business Rules.

These are usually dictated by the business at large and are applied to the Business objects.

Check digits in validation codes,

what algorithm is used for spelling tolerant searches,

how many items can be on loan to one person at one time etc.

They are centered on one or more business objects and the user (actor) does not necessarily have knowledge of them.

Also, Use cases and Business Rules have a many-to-many relationship. Using the ‘Mini-spec approach then forces a significant test of all the business rules  on every use case where they are used.   Testing the Business Rules formally on their own, reduces this duplication significantly.

Again, they can be subdivided:

2.1. Class and Attribute constraints.   These are mostly validation rules.

The application controller  should call the class whose data is being validated. This business object may then involve other business objects  as needed.

Any validation in the UI is optimisation. If should normally be checked in the business class as well, just in case there are several UIs or other access paths to the software and one of them fails to check.

2.2. Procedurre requirements. This consists of 3 parts:

2.2a Pre-condition  (Includes inputs)

2.2b Process (Algorithm)

2.2c Post conditions. (Includes Output)

Where have we seen these before? Any active process has them. That includes both use cases and program procedures.

The use cases are of interest to the users, who care about what they do.  These are checked in the User Acceptance Checks.

The procedures are of interest to developers and business staff who care about HOW things are done. These arte checked during the publicly interesting unit tests.

                     2.3. Constraints on class interactions.

Links between classes represent those that are important to this system.

Links between Business Objects represent the subset of these that are important relationships within the business perspective.

These tests can become very complex, and often need the domain (business class) diagram to understand. Without a diagram and when split  up in saya Requirements Catalogue, you often just have to give up, and just ‘tick the boxes’ for each test, without understanding how they work together.

 Conclusion

So now wehave two sets of requirements that are of specific interest to two groups of business staff.

1. the user requirements in the use cases. These are of interest to the user community; the bank tellers say.

2. the business requirements associated with the business objects in the domain diagram. These are of interest to the account database staff, reconciliation staff etc.

All but a few diagrams and some supporting wiki text form RELIABLE documentation that is included in the automatic testing used with every build. That is RELIABLE because the ‘fixtures’ (tests) as well as the production code are tested with every build.

The INDICATIVE documentation is nearly all supportive diagrams and secondary text. It is needed, but any errors are not critical. Text that describes a test, where the test has been altered, is often still good enough to tell you what it is about.

The RELIABLE documentation is also part of the system tests. They are the same. In normal systems, this work is done twice over.  Do we need Testers?  Yes, just to confirm that the wiki tables perform all the tests necessary; they normally have good experience at this aspect.

Of course the level of testing is itself dependant on the project and the risks they are prepared to take. But even for reduced testing, it pays to identfy the different types of tests. For testing military weapons, the catagorisation of the tests provides the precision that is required.

Which comes first, the test or the code?  It does not really matter. If the analyst has not yet written a test, then the developer can write one. If tests produced by any method  are spotted as being inadequate by a business staff member or a developer, then they can upgrade them, forcing a possible revision of the code.

The wiki allows all interested parties to see how well the system is working almost at a glance.

Apart from the addition of a strong reliance on UML, this method is very similar to the ‘Specification by Example’ approach described in his book by A Gojko (I have yet to read this) and in an article with the same name by Mark Crowther, who quotes Gojko.

http://www.cyreath.co.uk/papers/Cyreath_Specification_by_Example.pdf

 Mark used Concordian to replace Fitnesse.  It seems to need to have the results copied to a wiki, but has the distinct advantage that that tests that have been written for code not yet produced, are coloured yellow. In Fitnesse these test fail and so are coloured red; you can switch off the page that they are on.

Two Ways of Writing Specifications

For the object oriented analysis and development aspects of a system, UML was an outstanding success. Classes were defined with a good working set of textual description, (name, attribute, operation, associations and notes). Operations were expanded in the coding phase, and most modelling tools offered strong links directly into the application code.

However, for use cases, UML was NOT definitive about the data to be recorded. Most UML tools only had the basic fields (name, actors, associations and notes), but significantly lacked a fields for the ‘Goal’and ‘Scenario Descriptions’, which are key features for most use cases. (Enterprise Architect is one of the rare, but welcome, exceptions to this).

As a result, Use cases, had to be entered as ‘Notes’ and formatted in inadequate editors. Instead, the analysts turned to better text products such as Word for Windows. Diagrams were avoided and very soon, ALL the use case specification was in the one tool – Word for Windows.

Consequently, two ways of recording the specifications for a project evolved:

• Model the complete specification in a UML case tool with significant problems when working in text

or

• Write the complete specification as textual use cases in Word. I call these ‘Mini specs’, because to cover the complete specification, they had to be far more complex than use cases were ever designed to be.

The rest of this blog examines these two possibilities in more detail.

Model the complete specification in UML
Model the complete specification in UML, predominantly as annotated diagrams and try to work with the inadequate ability to handle use case text. Alternatively, have two documents, one the graphical picture and the other a word document for the use case text.

The graphical picture was based on;

• Business Domain Diagrams; a class diagram showing only business objects. These are objects that the business uses and recognise in their daily discussions cover any object in the business that may be involved with the system. It shows how they are associated with one another.
• Use Case Diagrams; A standard UML diagram showing how business objects (including people) interact with the system. These interactions enable the business to achieve it overall objectives expected from the system.

There is normally a many-many relationship between use cases and business objects, because both types of objects share many ‘Decision Points’.

• In use cases, the decision points create alternate paths, some very small and others large.
• In the domain objects, the decision points are usually constraints within the business class, such as validation, verification as well as algorithmic choices.

Splitting the use cases from the domain model reduces the number of duplications of the descriptions of these decision points.

Simplification was further enhanced by the division of use cases into smaller secondary use cases, so that most use cases easily met the ‘Magic Number of Seven’ rule (see my earlier blog, ‘The magic Number Seven’.) in terms of the number of features they represent.

Write the complete specification as use cases in Word
Write the complete specification as use cases in Word, predominately as numbered lines of text, and lists of ‘Specifications’ as statements defining decisions to be made by the software. The number of decisions wildly exceeds the ‘Magic Number Seven’, and so the word documents are, by that definition, ‘extremely complex’. Most Business staff agreed. Agile teams invented a new type of modularity, known as ‘User Stories’; these are usually very similar to the original concept of Use Cases.

For a good use case, one expects the complete description to be, on average, 3 pages long. I have worked on projects where they have grown to being 20 or 40 pages long. This complexity leads to further complications:

• Because the description breaks the ‘Magic Number Seven’ rule, readers request a ‘map’ showing the various possible paths as an overview. For this, the team usually request that the flow is shown as ‘Activity Diagrams’. There are good reasons to say that this is the wrong use of activity diagrams, although I can see the temptation.
• With NO Domain Diagram, decision points from that diagram are explicitly referred to in each use case, often several times over. Where one business rule is used in many use cases, that rule has to be either
1. i. referred to by some rule number and listed in a list of rules (which makes difficult reading)

or

1. ii. repeated in detail in each use case where it applies (which makes it difficult to test and maintain).
• Then some projects try to clarify the complexity by adding in additional data. They add in the database structure, user screens, non-functional rules and anything else that may be relevant. Each use case becomes in effect a mini-spec.
• The large number of ‘business rules’ then become un-testable, unless they are listed in a Requirements Catalogue. Such a document needs to have traceability to see where in any model it has come from, to why it was ever included in the model. The advantage of this is that every business rule can be signed off by the users as a formal requirement, and then signed off again when that business rule for that use case is tested. This disadvantage is that there can be thousands of them.

Summary
These two approaches, the UML Model (Use Case and Domain) vs the Use Case Mini Spec, have now become so distinct that teams adopt either one approach or the other.

This blog has identified the cause of these two approaches. It will be followed by other blogs describing the two approaches in more detail and which one to use for Agile environments.

See

• ‘Long Live UML Analysis’.
• ‘UML Analysis is Replaced by Requirements Analysis’.
• ‘UML Analysis is Alive in Agile Environments’.

Agile Software = ‘Fit for Purpose’

The Problem.

When discussing agile systems, the ‘Management vs Developer’ split is very common. However, I don’t believe it is really a ‘them and us’ situation. I believe that it is the way that the agile community is selling itself.

I saw the same problem in the early years of OO Programming. Developers believed that by using OO, development costs will tumble. They also believed that, by telling business that they will save them money, the business would come to them on bended knee. The Business did NOT; they did NOT appreciate ‘techy’. OO helped the Business, but a long time later.

The agile platform is very ‘techy’. The manifesto lists twelve principles, and considerably more than half of them would be considered by business to be ‘techy’.

For example, ‘Deliver frequently’ – the business mostly want only a couple of deliveries in the project’s timescale. It needs more explanation to convince them that they could possibly be better off with more. When we  deliver, IT WORKS! Because of this, it is suitable for the business to have a play with, to test it, to gain experience from it and, if they want to, change their minds about what it does .

Most of the other eleven principles are likewise.

---

The Solution

We should present ‘Agile’ along the following lines. There are three ways of purchasing a system:

1. ‘By Reputation’,

2. ‘By Specification’ and

3. ‘Fit for Purpose’.

Agile emphasises the latter approach.

• The business outlines what they want, complete with some ‘ifs and buts’.
• The team produce the highest priority AND DELIVER IT.
• The business can then find fault with it, change their minds on what they want or just accept it.
• If the Business wants changes, then low priority items somewhere else in the list of requirements will NOT get produced, but that is NOW a business choice. The Business decides what ‘Fit for Purpose means’ as the system grows.

There are also benefits towards the end of the project. There is always uncertainty in estimates and if the budget runs out before the originally agreed product is complete, the Agile approach offers a significant advantage.

• On non-agile (contract) based systems, the business will be required to pay more to complete the specification. Such ‘ Contingency payments’ can be very large. Also, because there has been NO compulsion on the developers to regularly produce ‘deliverable’ releases, this extra cost may be necessary, just to get a single deliverable sub-set of the system. The alternative is a failed project.
  

• With Agile, you finish when the budget does. True, the team must make sure that the last sprint is ‘deliverable’, but that is normal. Backlog items NOT done are NOT in the delivery. Now the decision is back in the Business’ hands. If they want those ‘NOT delivered’ features, they will have to use the contingency, but if they really do NOT want luxury, bunce etc, they can complete the project now at NO extra cost.

The importance of ‘Agile’ to a business is that it puts the business in charge.

The Business decides just how ‘Fit’ the system is for their ‘Purposes’.

It is NOT some ‘specification’, or ‘reputable’ computer team that forces the decisions. In order to deliver in this Agile manner, the ‘techies’ will decide that the twelve principles are critical. That bit is the ‘Techy’ decision.

But the Business make the business decisions.
The Business end up controlling:

• the product delivered,

 

• the expenditure

 

 

• and the delivery date.

 

The Business is back in control.

I rarely hear Agile presented this way.

It is much more attractive to Business.