Developing Functional Specifications based on the UML Model

A few days ago I found this white paper I did around 2004 way before I started really blogging:

The Process Overview

Use-case to Specifications is a processing using UML use-cases to identify user requirements and model systems to be able to properly define functionality. This document is intended to serve as an execution based walk-through of this process.

As background: ‘The Unified Modeling Language (UML) is a language for specifying, visualizing, constructing, and documenting the artifacts of software systems, as well as for modeling business and other non-software systems. The UML represents a collection of best engineering practices that have proven successful in the modeling of large and complex systems.’ ~OMG Unified Modeling Language Specification

Use-case – Basic’s

In this process we are focusing on the use of use-cases to identify requirements. The goals of building a use-case is to first identify the actor. This is the person or entity performing the actions described in the use-case. In some cases, the actor is simply a component of the system and not necessarily a user or consumer of it. Second is to identify the goal or what we are looking for the end result to be. Third, and last, is the process in which the actor will take steps to reach the end result or goal. This process interaction is typically described in story form and contains a complete end-to-end walk-through of the actions taken by the actor to reach the goal in the proposed system. To this end, it helps to think of a use-case as a stand-alone story that isn’t dependent on any outside parts to be considered complete. Use-cases serve as a primary tool to help us work out system interaction issues, such as the way it’s accessed, how a part of it might be used or perceived, or how a particular aspect is intended to operates. Basic use-cases will include the following elements, all of which are derived from the overall story-line created:

Name
Actor
Triggers
Story
Steps
End conditions
Failed conditions
Success conditions
Alternate scenarios.

Use-case’s

To develop a use-case we first need to start with an actor. There are several ways to determine an appropriate actor. One way is to ask a couple of basic, but key, questions: 1. Is this actor a component of the system, like a class or object set, or is it another type of entity, such as an administrative or end user. 2. Is the actor a consumer of the proposed system or does it live and/or work within the system. Second, we need to come up with the goal. What is the end result we are expecting from the interaction process? The next step is to develop a story that describes how this actor interacts with the proposed system in order to reach the end result or goal. The following example uses ‘Microsoft’s ACME Project’ or MSAP as the proposed system and an end user “Joseph” who has specific privileges within the system. The goal in this case is to register for an existing course.

Example:

“Joseph, a gold level user and technology buff, has just learned that a new course is being offered for his favorite technology: C#. He immediately rushes onto the MSAP and signs in using his Passport credentials. Joseph then selects the MSAP Center link from the left-hand navigation menu. Once there he is able to quickly search for content relating to C#. Joseph locates the course in the search results that were returned to him and clicks the “Register” link. Joseph is able to get more information on the course while reading through the summary page. He decides that this class is definitely worth while and proceeds through the registration process. Once registration is complete he receives an email confirming his successful registration. Joseph marks the course date and time in his calendar and quickly gets back to his day-to-day tasks.”

Summary:

The story in this example use-case is fairly refined. When we carefully look at this story it identifies a number of qualities about the actor as well as the process used to reach the end goal. From this story we can derive requirements and even data elements needed to ensure that the functionality described matches what was proposed to be built.

First we see that we have given our actor a name. This allows us to reference the actor more easily throughout the use case. From this story we can see that each relevant step our actor goes through has been described. Additionally we can derive actions that “trigger” other actions and can see the basis for some assumptions that were made. As the story’s end draws near we take note of end conditions and finally, after the basic story is completed, we can assess whether or not there are alternate scenarios and even failed conditions that need to be documented.

Derivative Requirements

Once we have worked out the use case we can derive requirements from this. Let’s start with data elements… In the case of the above use-case we can identify the fact that we will need a user that has the following attributes:

User name
User level
Skill set(s)
Course(s) registered for
Course(s) history (assuming we want to keep track of what happens)
Language (if this is used internationally i.e. is he viewing this in English or does this apply to any local? )
Passport account
PUID
Partner
e-mail address

So we now know that the system will need at least the ability to define the above elements and logically we can think of this as an object.

As to the system, we know that we will need to have gold users be able to login via passport then search and finally register for events. From this we know that MSAP will need to use passport at some level, as well as have built in search functionality and registration functionality. In identifying these elements we also then know that we need to track these data elements as well in the system. So that means we need course information or a ‘course’ object that has search functionality and we need to be able to tie that into registration. An instance of registration would also then be associated to a user and to a course or event.

From this point we are able to identify the basic groups of functionality as well as document data elements from just one use case. These become our derived requirements based on developed use cases.

Building Specifications

From these derived requirements we can also do flow diagrams and sequence diagrams for each use case and this feeds our design process by making it easier to come up with object models and sequences etc.

To focus on specifications, we need to take from the original business requirements and data from our use cases and any requirements list to build functional specifications. Typically organizations have a template of sorts. Microsoft is no different with excellent templates that allow the collected data to be plugged in quickly and effectively. Use cases can be prioritized by this derivative process which in turn prioritizes the feature requirements. In our above use case, from the users stand point, the ability is needed to search and find classes and be able to register. If a user can’t do this then there would not be much point in the example software.

Regardless of templates or other things a functional spec should include all the critical use-case stories or summaries, a feature list, prioritization of features, any external requirements or limitations, assumptions, critical data, issues/risks and a summary of the document.