Capturing Software Requirements, User Stories, User Interface and Entities – An Agile Approach.

FSS General Software Development

Rewriting software is expensive, so the more you can get right first-time the better. To get it right you must discover the real requirements –that is understand what the project stakeholders really need. To get the customer’s vision written down (with enough detail so that a development team can implement it) requires a process that the customer can understand and actively contribute to thus yielding requirements that a developer can then work with.

This article identifies one approach to solve this problem, namely the use of three specific and different techniques to get a comprehensive picture of the requirement that is to be implemented.

This approach is designed to be compatible with the ‘Agile software development methodology’, in that it supports the project envisioning / getting started phase, but also produces ‘work items’ that can be prioritised and developed , tested and released in an iterative manner. This approach can be adapted to suit more formal iterative development methodologies, by adding more rigour, formality (and time) increasing the emphasis on documentation and reducing the emphasis on development communication.

This approach will not suit all software project types, but we have found it to be effective for small to medium sized custom business software projects.


Approximate percentage time spent in each of the three requirements gathering techniques. We advocate concentrating on one technique at a time, per system functional area, however flitting between techniques is inevitable because whilst working using one technique requirements best documented in another are frequently discovered .

Guiding Principles during the Requirements Phase

  • Use “real-world” concepts – sometimes there is a tendency to over abstract, or for customers to define requirements based on how they have bent things to work with a pre-existing restrictive system rather than in terms of real world things. Ensure requirements relate to tangible things e.g. documents (say invoice), staff roles (say receptionist), data records (say stock levels).

  • Requirements come from project stakeholders – customers should lead the activity, the supplier should facilitate, by managing the process and asking the right “what if” questions to tease out the knowledge.

  • Use the right tool – when recording requirements any delays in recording the information slows the process down and breaks trains of thought.

Capturing Data Requirements – Entity Modelling

Entity modelling is used to record the data that needs to be stored, and the historical facts that need to recalled at a later stage. Entity modelling also documents the relationship between entities, their primary key (what makes a record uniquely identifiable). If the system is to have a database at its core then we would recommend that an articulate DBA works with the project stakeholders to document their “real world” entities and also record the primary keys, descriptions, relationships, etc at the same time.

Entity modelling is often best done in four phases.

  1. Identify the functional areas and their priorities and interdependencies.

  2. Starting with the functional areas with no dependencies on others (and in priority order) record what the key entities are, with meaningful names and descriptions.

  3. Add in the entity attributes, primary key(s) and relationships.

  4. Optimise the entity model so that it is easy to implement and maintain and good for performance – DBA (for database solutions) or a Coded Data Expert (for embedded) is required.

Capturing Functionality Requirements – User Stories

User stories record the activities that different types of operators do and their effects on the system and the data. Operators may be particular staff roles (say bookings manager) or other people that interact with the business (say customers) or even other triggers (say a timer).

Personally I believe that a user story should be made up of a title, a priority and an explanation. The explanation may include alternate scenarios (e.g. if user cancels). Often it is good practice to capture the user stories as just “titles” to start with, then prioritise them, then add on the explanation in a “conservation phase”.

User Story Titles

A good user story title includes the following parts:

  • User Role(s)

  • Clear Verb

  • Outcome and Benefit

e.g. “A Sales Clerk records a new Sales-Order from a customer with Products and Quantities, thus starting the sales process”

User story explanations

User story explanations should be CUTE (Concise, Unambiguous, Testable and Estimable).

e.g. “Create new sales order for selected customer (or new customer), adding on required products, quantities, prices plus any special requirements as free text”

User-Stories versus Use-Cases

Use cases tend to be more formal, longer and define requirements in more steps. They are part of the UML standard and are supported well by software modelling tools, sometimes in an iterative development methodology they are packaged up as a deliverable into the next stage as a relatively unambiguous and complete specification. Use-cases lend themselves to immature software development teams, safety critical software and outsourced software development.

User Stories are lighter and software developers need to apply some intelligence to pick out derived user-steps. User stories must be supplemented with other artefacts (e.g. entity models, user-interface brainstorming and latterly acceptance tests). User-stories are best for mature software development teams, where there is continuity and good communication between the requirements gathering and development personnel.

Teasing Out More Requirements – User Interface Brainstorming

The activity of sketching out ideas for the user interface quite often helps the customer think about how they would like to operate and can often lead to the discovery of “special cases” that need to be catered for.

User Interface Brainstorming is often done best by explaining the processes (including demonstrating software previously delivered and its user friendly features), and then in four phases for each major functional area.

  1. Identify screens

  2. Categorise screens as basic, or complex

  3. List the features needed on each screen

  4. Draw a sketch

Once these tasks have been completed, it is often worth doing a quick consolidation exercise, to maximise reuse and simplify the screens where possible (an experienced user-interface designer is required for this task).

Identify screens

Using the entity model and the user stories, identify the screens required, think about staff roles and the tasks that each role undertakes. For each screen put a title on a blank word document page, or at the top of a page in a pad of paper.

Categorise screens as basic, or complex

Basic screens are easily explained by a user story and the entity model, e.g. if you need to be able to list, create, update and delete customers you may be able to identify 2 screens and just link them to user stories, with the entity model there is no more specification needed.

List the features needed on each screen

Keep sentences very short and ensure that they are testable, a good way to do this is to simply cross reference user stories, or use bulleted lists. Also identify the entities that are displayed, or edited on the screen. Make use of a recorded set of acronyms to save time e.g. C, R, U, D for Create, Read, Update & Delete, ROL for Read Only List, etc.

Draw a sketch

Using rectangles and text boxes in a word processor, or drawing tool (or a pencil and paper) sketch the key features. E.g. rectangles to represent where read-only lists of data are to be displayed. Rectangles representing selection of a choice of data from drop downs, key action buttons, etc. We advocate using this sketch for feature identification; for the best possible usability, look and feel, dedicate the final layout design to an experienced user-interface developer.

In Summary

Requirements specifications are the key to producing great software for a competitive price. Formal specifications take too long, and are often flawed, an Agile approach using a mix of entity modelling, user-stories and user-interface sketching is a better way forward for a lot of software projects, provided that the development team is mature and used to Agile development techniques.

Flexible Software Solutions offers software process improvement advice, software tool integration services and User Interface development support throughout the UK and beyond contact us for more details.

We believe this article (although brief) to be accurate. If you have comments or suggestions, or believe there are inaccuracies in this article – let us know, we appreciate your feedback.

The author (Rob Harwood-Smith) has been developing software for more years than he cares to mention, his experience ranges from embedded safety critical software, large scale database systems and also to custom business software solutions. After a few years as a software consultant Rob joint founded Flexible Software Solutions.