Archive for July, 2010

Use Case Style Issues

July 28, 2010 Leave a comment

Some more notes, following a review of my team’s experience of writing a set of use cases during a recent round of development, focusing in some of the stylistic issues we encountered (as in writing style, rather than layout).

We found that converging on a consistent house style was surprisingly difficult. The following are some of the pitfalls we found we spent time trying to agree, or had to revise. I hope this may help as a pointer to others trying to hit upon a common use case style for the first time:

Active voice. Maintaining the active voice in steps (“the system displays a list of customers”, not the passive “a list of customers is displayed”) turned out to be surprisingly hard. As our use cases covered entirely back end processing and would take the repetitious form “system does x”, we decided a better approach was to write “the system does the following” then a set of numbered steps in command form (“determine this, update that”).

Alternative Flows. Our concern here was the layout: which way structures the flow most clearly? A purist’s approach would be to pull out all the alternative flows into separate sections, to leave the main flow showing just the standard scenario. Our developers much prefer a single nested flow of statements in the order they would write the program. We decided that where it was a simple if-then-else the alternative could go in the main flow, and where either the alternative path contained multiple steps or it omitted several steps in the main flow we should define a formal Alternative Flow.

Trigger, preconditions and initial step. We found a clear and consistent definition of these three took some effort to understand. Preconditions are statements that the use case can assume are true and need not test explicitly again – but we struggled to work backwards to identify them in a consistent way. Related to this, we spent a lot of time trying to agree how to handle the call from the previous use case. It’s not a precondition (although some of the team thought it was as it sets the data up in a particular way) but is it a trigger or the first step of the main flow? This is particularly true if the call could come from multiple places. I’m not sure we quite got it right. In practice triggers and the first step overlap

Business Rules. Our use case documents contained business rules, which purists would say shouldn’t be here. We write these as functional statements that can be tested, defining the detail behind the simple statements outlined in the main flow steps. We defined all data with reference to the Logical Data Model. We allowed pseudocode in rules if that was the best way to describe it. We also decided that there should always be a statement for each step, to make sure it was tested, even if it effectively duplicated the step text without adding much to it. On review some statements were deemed not to be strictly functional, but if they contained useful background information were rewritten as preconditions or assumptions or inserted as notes.

In deciding how to resolve these issues, we kept our audience in mind – in our case the Use Cases are being written primarily for developers and testers. That has influenced how we have chosen to phrase things – e.g. the use of pseudocode in rules, or referring to all data items via the Logica Data Model, neither of which might be appropriate for a non-technical audience. On another project, we might make a very different set of decisions.

Some other views

Categories: Work Tags: ,

Lessons from Undercover Boss

July 21, 2010 Leave a comment

I just happened to see the start of last Thursday’s Channel 4 fly-on-the-wall documentary Undercover Boss, and it held my attention enough that I watched the rest of the programme

I am not going to provide a précis of the episode (but see here) other than to say that the chief executive of Best Western Hotels, David Clarke, went undercover as a “trainee” performing some basic entry-level jobs in three of his hotels. Newspaper reviewers have been predictably cutting – “[Clarke] discovers the usual corner-cutting and staff discontent and goes about remedying the situation with all the alacrity of a man being filmed while trying to show his business in a positive light. The cameras kind of ruin this one” from The Guardian is typical – but I thought he came across relatively humanely. Despite the flaws of the format, it was revealing enough, and I drew three lessons from it.

The first is for senior management. Clarke was surprised by how messages from the centre fail to get through to staff on the ground. Best Western had invested heavily in an advertising campaign, and had been pushing the message out hard (or so they thought) to their member hotels. Despite this, hotel staff just didn’t seem to be aware of it, or indeed of anything much about Best Western at all. This was true even of top performers who were otherwise doing an excellent job.

This may have been news to Clarke, but not to those of us who are at the sharp end delivering a service to customers. Communications from the centre, however well intentioned, often seem irrelevant to our daily situation. Sometimes it is if they are in a foreign language – branding and marketing messages are often written by management for clients’ management. I was surprised how genuinely surprised Clarke appeared.

The second lesson is a reminder to anyone concerned with monitoring quality, about the importance of random QC checks. The programme exposed a process failure; one of the hotels had failed a quality inspection, and the handyman was preparing for the re-inspection by swapping defective equipment in failed rooms for identical items from rooms that had passed, because the inspector would check only that defects had been fixed. It highlights that people will always game the system, and will do what they can to score against what’s being measured, not what matters. This is particularly true of poor performers.

Finally, a reality check for me. It was a reminder that there are many people on little above the minimum wage who nevertheless put in unpaid effort beyond the call of duty to satisfy the customer, out of professional pride, even though they get little/no direct personal benefit from it (except maybe not losing their jobs). After working for so long in IT, where staff are relatively well-paid but cynical, it was a reminder at a time when pay rises are rather thin on the ground that we could all be much worse off.

Categories: Work Tags: ,

Thoughts after modelling with Use Cases

July 13, 2010 2 comments

This was the first time for several years that I started a new round of development by modelling use cases. The team were familiar with the concept but had mostly not worked this way before, and at the outset were not entirely sold on the approach. After completing the first batch of use cases we held a review to see how we found it and how we could do it better.

Our situation

This was a significant enhancement to an existing system. We first tried to define all the use cases, to scope out the size of this significant and complex process. We expanded three new high level use cases into about 15 lower level ones.

Our intention was to complete an overview of the use case model, and also define the Logical Data Model (at least to entity level), before delving into the detail. Early availability of the team meant we started working on the detail sooner that was ideal in retrospect and wasted some effort, but the team members would otherwise have had nothing else to do.


These were for system use cases describing entirely back end processing where the only actor was the system. Some schools of thought say use cases shouldn’t be used in this situation at all. We found it valuable as a way of identifying the main components, especially common functionality, and then working out the interaction between them.

A single use case diagram turned out to be surprisingly useful in providing a visual summary. We also found it was ideal for tracking who was working on which one – just by writing the author’s initials on the oval in the diagram! I have always been cynical about the value of diagrams, but was proved wrong in this case.

We got the granularity roughly right; when we reviewed the model, the only change agreed was to extract an alternative flow into a separate use case. There was one other use case which some of us (including me) thought was too short but after a brief discussion it was clear there was no agreement. I curtailed discussion and stuck with the status quo as in my view if something isn’t obviously wrong then it is better to leave it as it is, rather than spending a lot of effort trying to get the model “perfect”.

Aligning the team to a common style was surprisingly difficult. This applied both to simple writing style and formatting issues, as well as agreeing what the content of certain sections should include. This could fill a whole post in itself. Before starting I held a quick overview session, then each member of the team wrote a couple of use cases, and then they were all reviewed by someone else, so we could all learn from each other and gradually coalesce around a standard. Ultimately we concentrated on the content, not the format.

How best to organise the documentation? We tried to find the happy medium between one long use case document and one per use case, balancing the ease of availability for update and the overhead of maintaining multiple small documents. We agreed that related use cases should be in the same document, as often the same person would probably need to update several of them at the same time. This meant between two and six use cases per document.

The team view

It took a while for the team to become used to the tighter constraints imposed by a formal use case structure. But once we had managed it, we agreed that it imposed a rigour on our thought processes, resulting in a very clear set of functional requirements.

The developers like it as it is clear what they must now develop. By the time we had worked up some complete documents, they were sufficiently detailed to code from without needing to write any further technical specifications. It proved quite easy for one of the developers to take a set of use cases and produce a sequence diagram.

Overall, we have made good progress in establishing a standard that will help us to deliver what the client wants. On to the next set!

Categories: Work Tags: ,