Chapter 2    Some Of The Reasons For This Work

My website http://www.umllmu.com contains requirements training material for a complete process from business modeling through to systems analysis and high level design. It also includes templates for, and examples of, the artifacts that are created as a part of this process. This work puts all of that material (and more) together in a single document in order to describe the complete process. Although the online material is specific to the Rational Analysis tool suite, Rational Software Architect and Rational RequisitePro, this work is more generic and makes use of MS Office in the most part.

This document attempts to explain the subtleties and ideas behind the complete process and also to describe everything in software development tools independent process (by tools independent I mean that, as a minimum I expect the analyst to have access to MS Office). In particular, you will need MS Word, Excel and Visio, or equivalent applications.

2.1    Requirements

I have been working with requirements for more than 20 years. To be honest, it was several years before I understood the true purpose of requirements. The enlightenment came about when I was tasked with documenting a presentation to my colleagues that described the characteristics of a ‘good’ requirement. The characteristics that the team came up with included:

·         Complete – A functional requirement should describe all observable inputs, all observable outputs, when it can occur, who (actor that) is allowed to initiate the requirement and the maximum time that the requirement is allowed to complete.

·         Consistent – The requirement should not be in conflict with any other requirements for the project. For example, if one requirement states that all user inputs will be processed within 5 seconds of entry and another requirements states that system shall respond to a particular user input within 10 seconds, there is a conflict in the requirements.

·         Correct – Are the requirements specifying a solution that the business wants implemented?

·         Design independent – If there is another way of specifying the requirement which will result in a different solution to the problem, then it probably contains design information and should be abstracted out to allow for all possible design decisions. For example, stating that when the main window is closed that the system will logout the user etc, is too detailed. Supposing we decide not to build a windowed application? A better way to abstract the requirement would be to say that when the user exits the application that they will be logged out, etc.

·         Feasible – Is it possible to implement the requirement within the specified time and budget? (And, we might want to ask if there is there a positive return on investment (ROI) for implementing this requirement?)

·         No negative requirements – Stating the system ‘shall not’ do something is either untestable or irrelevant. The requirements state what the system will do; anything else is out of scope. For example, instead of stating that something shall not be ‘red’, state the colors that it may take. Irrelevant example; stating that the system ‘shall not’ allow a user to view user information, is already covered by a requirement that an administrator shall be able to view user information. The fact that it has been stated that administrators may view this information, excludes all other actors, unless explicitly stated. A rule of thumb is that the system does nothing unless it is stated as a function of the requirements.

·         Relevant – Is the requirement in scope for the current effort.

·         Testable – Is it possible to define specific ranges of inputs and outputs for the requirement such that when the implementation of the requirement is executed all inputs cause the system to produce the specified outputs, otherwise the implementation of the requirement fails?

·         Unambiguous – The requirement should not contain any words that are open to interpretation. This includes all adjectives and adverbs, unless they are clearly defined in a project glossary. For example, the system shall allow ‘many’ users to change their profile. Unless the word ‘many’ is explicitly defined this requirement has little meaning; and it can be satisfied by allowing exactly 2 users to change their profile and no more.

2.1.1     Functional Requirements

In addition to the above, functional requirements include the following characteristics:

·         Precondition (optional) – when can the functional requirement execute? The precondition specifies what state the system must be in before the requirement may be initiated. Not all functional requirements are able to execute at any time. If using a use case approach to writing functional requirements, the use case precondition states what use case(s) must have completed prior to this use case being able to initiate, and each step in the use case has an implied precondition, which is the previous step in the use case. (Sometimes the precondition may be implied by the wording of the requirement, in which case it does not have to be explicitely stated.)

·         Time to complete – if a functional requirement does not have an associated maximum time to complete, then if the implementation of the requirement does nothing it will never fail testing. If it never fails testing and never does anything it will never get deployed into production. Again, using a use case approach, the whole use case may be given a time to complete, or you may specify time to complete for individual steps. If a group of steps are assigned a time to complete, and that time expires during testing, then every step in that grouping is considered to have failed the test.

2.1.2     Non-Functional Requirements

Non-functional requirements additionally include the following characteristics:

·         Reference to a functional requirement – non-functional requirements place constraints upon functional requirements. Functional requirements may include the meaning of the non-functional requirement in their specification. The reason non-functional requirements are specified separately is because they often impact many functional requirements. We do not want to duplicate the requirement. Therefore it is called out as a separate requirement and references the functional requirements that it impacts.

2.1.3     Definition of a Functional Requirement

From Wikipedia: ‘In software engineering, a functional requirement defines a function of a software system or its component. A function is described as a set of inputs, the behavior, and outputs (see also software).’

When not employing use cases, I use a template for specifying requirements of the following format: 'When' in a certain state* 'and' 'upon’ some externally visible event occurring (the trigger), ‘the system shall’ do something externally visible, ‘within’ a certain time frame.

['When' in a certain state is optional, and if omitted means that the requirement is valid in under all circumstances, i.e. it has no precondition.]

For example, 'When' the ATM is free, 'and upon’ a customer inserting a valid debit card into the ATM slot, ‘the system shall’ request that the customer input their PIN through the ATM user interface, ‘within’ 5 seconds.

(The 5 seconds of course applies to the system and not to the customer entering their PIN.)

Here are some examples of requirements that do not satisfy the template. See if you can figure why before reading my answers.

1.      When requesting a customer PIN, and upon a customer entering their PIN through the ATM UI, the system shall verify that the PIN is correct for the card, within 5 seconds.

2.      Upon verification of the customers PIN, the system shall inform their customer that they may select an action from the ATM UI, within 5 seconds.

3.      Upon dispensing cash to a customer, the system shall send a message to the Banking System requesting that the customer’s account balance be deducted by the amount dispensed.

4.      When a customer card is inserted, and upon the Banking system receiving a deduction message, the system shall give the customer their card back, within 5 seconds.

5.      Upon a customer entering the 'Display Balance' command, the system shall request the customer balance from the Banking system, within 5 seconds.

In my opinion these requirements contain the following errors:

6.      ‘Verify the PIN’ is not an externally visible action. If the PIN is valid, the selection screen will be displayed. If the PIN is invalid, an error message will be displayed. The first case was already covered by the original requirement when it included the word ‘valid’. We need to add another (separate) requirement to cover the invalid situation.

7.      The trigger is not externally visible. We cannot observe the system verifying the customer PIN. In fact the act of ‘verifying’ the PIN is a design decision. Our designers might equally decide that the PIN is verified by the Banking System. In fact, in reality, it probably is.

8.      No time frame specified. The banking system is going to lose a lot of money if the ATM sends out deduction requests once a year.

9.      The trigger is not an event that the ATM system can recognize. The Banking System has to somehow inform the ATM system that it received the message. It is upon reception of this event that the requirement initiates.

10.  No precondition. The customer must first have entered a valid PIN, otherwise the system cannot be sure whose balance to request. 

2.2    Good Practices

This following sections contain rants and recommendations for good practices, useful not only for when delivering software, but that can also be used any time organization is required.

The most common improvements that can be leveraged on any (some on every) development process it has been my experience to be involved with, are the following:

·         Duplication - Copying and pasting, work (text or diagrams) from one place (or document) to another.

·         Ambiguity - Using the same term(s) with more than 1 meaning on the same project.

·         Inconsistent Documentation - Documents that supposedly describe the same information (or have similar purposes), but have different content. Deviating from the approved document template.

·         Unnecessary Documentation - The creation of documentation, without first identifying an audience.

·         Document Content Organization - Related to unnecessary documentation. This rant is concerned with putting the right information in the right place in the document.

·         Ad Hoc Procedures - Concerns having a standard set procedures for handling files and making sure that everyone on the project understands how to use them.

2.2.1     Duplication

How often do you see the same piece of information documented in 2 places? I am used to seeing requirements information copied into design documents; whole sets of requirements being copied into a test repository and diagrams copied from one document to another. Unless you employ a strict change management control system that includes a traceability scheme, this sort of practice is going to prove expensive, for 2 main reasons:

The work of maintaining information is being done twice.

More expensively, if one artifact changes and the other doesn’t, how do we know which is correct?[1]

Employing an automatic update scheme, a traceability scheme which shows when something has changed or a strict configuration management scheme which prevents artifacts from being changed, will go some way to solving the duplication problems, but again they are expensive.

Rather than spending time and money in trying to control duplication; I recommend, ‘Don’t Do It’. Here are some schemes that can be used to prevent duplication:

·         Put the information in a central repository and reference it with hyperlinks.

·         If you must have the information displayed in two separate places, use Object Links and Embedding (OLE). Extract the information from both artifacts, place it in its own document and embed the document as an OLE.

·         Use document generation tools, such as SoDA, to insert duplicated information into your documents.

·         Ask yourself the question; ‘Do I need to put this information here?’ Or, ‘Can I reference the same information, located somewhere else?’

Do not copy, either use a link or make a reference if you absolutely must have it here.

2.2.2     Ambiguity

How many times have you experienced a disagreement between colleagues, only find out later in the project that they were both correct. Chances are that they were using the same word, but both had different ideas of its meaning. I can derive hours of entertainment by playing word games with my friends, by picking a word they are using and purposely give it a definition that they are not thinking of. The important thing is that no one definition is incorrect, but it may be different.[2]

For example, ‘Closing the door’; everyone knows when a door is closed and when it is not – don’t they? I might argue that no 2 people have exactly the same definition of a closed door. I might argue that a door that is ajar by an inch or so is actually closed. This is not strictly incorrect unless all parties involved in the conversation have agreed to a definition of a ‘closed’ door.

Obviously, this is not the sort of discussion that you want to have in the work place, but it is going to happen if not everyone has the same definition for an ambiguous term. Ok, you may say, but everyone in the work place has a pretty good idea (or at least a close idea) of what constitutes a closed door, such that we do not have to define it. Well if you are working for a word processing software company – yes; but if you are writing software for an application that controls submarines, and you want me to ride on that sub, I hope that the word ‘closed’ when referring to doors, was well-defined early in the development process.

My recommendation is to maintain a glossary of commonly used terms on your project that could cause confusion if open to several interpretations. We know that ideally requirements should not contain adjectives or adverbs, such as near, far, slowly or quiet. Sometimes we need to use these words on a project, in which case they should be defined in a glossary. For example; if we often use the word slowly, then define it as; Slowly – implies that the vehicle is traveling at less than 10% of its maximum speed.

I find that a RequisitePro project works well for maintaining a glossary of terms. MS Excel  and other spreadsheet applications may work equally well; so long as you can order terms, give them several attributes (acronym for example) and link them (as synonyms of each other, for example).

Next time you are in a disagreement with anyone (be it at work or at your local), listen to the words that they are using and try to figure out which ones are having a different definition applied to that which you are using. You’ll come to an agreement eventually (that is of course unless their objective in arguing is to maintain the argument).

Whenever possible, do not use a word (or term) that is ambiguous, because you can be sure more than one interpretation will be used.

2.2.3     Inconsistent Documentation

If you are writing a letter to your mother, it is fine to create a new a new blank document, type your random thoughts, add highlighting, colors and emphasized text where you want to make and get a point across, and basically format the document with any creative ideas that you feel appropriate.

When working with documents in the workplace, ad hoc formatting is probably not appropriate. Yet I see so many requirements and other technical documents that were written by people who thought that they were writing a letter to their parents.

Imagine if every programmer on the development team wrote source code using their own personal coding standards. Nobody would be able to maintain someone else’s code. It should be the same with documentation. Every document should be written from a predefined document template that includes documentation standards (instructions for use), a consistent set of styles and properties.

The problem not only applies to textual documents, but also to diagrams. UML for example, defines a set of artifacts in terms of a set semantics and rules that apply to that artifact. (As far as I am aware) the icons used to represent an artifact are not defined within UML standards. Not only that, but UML allows the stereotyping of defined artifacts, which in turn leads to a customized representation of the artifact.

An example, I might be, using an arrowhead to indicate the initiator of a use case (which I do), and someone else using a dashed line to indicate the same thing. Now there needs to be an explanation in each document of the meaning of which notation that is being used. Not only that, but if both diagrams contribute to the same document, you are going to confuse your readers.

Use a set of rules for identifying a particular meaning on a diagram. If there is no rule for it, then make one up and explain what the particular notation means (although the more project rules there are , the less explanation needs to be added to the diagram or document). Say for example, you wish to highlight parts of a diagram to indicate that they are candidates for change, but there are no project specific rules for indicating how to highlight changing components. Then go ahead and shade the items (or whatever highlight you prefer) and explain what the highlighting means.

Which leads me to; the number of times I see a figure in a document without, not just a description of the figure, but not even a reference to it. Why did you put this figure here, if you are making no reference to it?

If there are 2 ways of doing something, pick one that works, describe it and stick with it for the length of the project.

2.2.4     Unnecessary Documentation

The first section that I look for in a document, is the paragraph that describes ‘who this document is written for’ and ‘what benefit they can expect to gain by reading this document’. If I do not see my role, or I do not see any benefit from me spending time reading the document, then I have to ask myself the question, ‘Do I want to read this document?’ I want this information to be displayed to me asap, such that I waste as little time as possible, reading a document that is of no interest to me.[3]

When I review a document or document template, another task that I might perform, is to consider each section in the document and ask the question, “Who asked for this information to be entered into this document?’ Or, another way of putting the question is; Who is going to read this and get value from it?[4]

Typical subsequent sections of a document I have seen that need this question applied include:

·         Document History – How many readers want to know what changed between versions from 1.1 through to 1.15?

·         Definitions and acronyms – leave them in the glossary, nobody needs to read these in the document. If anything I want to be able to reference these while reading the document without having to leave the current page. (See also ‘Duplication’.)

·         References – Put the reference in the section that uses it. I do not need to see a separate page containing a complete list of document references. I am not going pull up all the referenced documents and have them prepared in case I come across documentation that makes reference to one of them.

Before you document something, find out who it is that needs this information documented.

Which leads me to ..

2.2.5     Document Content Organization

On a related issue: There are tools for recording document versions. Any decent tool that is intended as a central repository for files of any type will record the version of the document and allow the author to add comments to the version. Such tools include SharePoint, LiveLink and ClearCase amongst many others. So why is it that when I open most documents, one of the first things to be presented for my reading pleasure is a table containing a version history. Honestly, I have seen version histories that span many pages and are quite detailed. They explain every change that has been made to the document over the last Millennium. Who wants to read this stuff, and why is it the first information that is presented to the reader after getting past the front page? If we are using a document management system on this project, (and I certainly hope that we are) all of the version history information should be documented inside the tool. Why is it being repeated in the document?

Many years ago, before the advent of intelligent document comparison tools, this information may have been useful in the front of the document. It allowed to reader to determine which parts of the document have changed since the last time they read it. Today, any Word processor worth purchasing will inform you what has changed since the last time you reviewed the document.

I realize that there are some roles on the project to whom this information is important, QA or auditors, for example. If you must publish this information with the document, put it in an appendix to the document, or better still, extract it from your document management tool into its own document. Then distribute the version history document only to those people that want it.

Now that the version history is out of the way, what do we now see when we open the front cover of the document? The table of contents. It is useful to be able to easily locate this, but I question whether it is the first piece of information that I want to read. What I need to know, as soon as possible is, ‘Should I be reading this document?’ What is going to answer this question – the Introductory material in section 1.

1.      The first question I want answered is; Is this document describing a system that I am interested in?

2.      The second question is; Is the information in this document pertinent to my relationship with the application?

3.      The third question is; What information am I going to get from this document?

4.      Fourthly: What is my responsibility towards the information in this document?

Hopefully the answers to these questions become apparent as soon  as I open the front cover of the document.

Put the appropriate information in the appropriate place and avoid showing unnecessary information to the wrong people.

2.2.6     Ad hoc Procedures

I believe that software development should be more of a science and contain as little artistry as necessary. It is great to come up with ingenious processes and guidelines for developing your software, but if they impact your colleagues you must get buy-in from everyone who is impacted before you start using them.[5]

Some people achieve satisfaction by getting a compliment for a ‘job well done’, some for a ‘working really hard’ others for ‘being a team player’. Nothing gives me more pleasure than having a colleague answer ‘Yes’ to the question, “Did I make your life easier?”.

Recommended procedures for working with documents should be documented, available and approved by all users of those procedures. Examples of these procedures include:

Location of document templates and how to access them.

The purpose of the document template and where to enter information into the template.

Documentation numbering and versioning conventions.

How to check out from and check in to a document repository system.

How to use the product or project glossary.

The purpose of the styles and properties that are used by a document.

The process for baselining, or creating a new version of a document.

Document your procedures and make sure that everyone that needs them understands them and has easy access to their documents.

2.3    Project  vs Product

I recently attended a training course on software development methodologies .. well 1 method in particular.[6]  The course was very educational and I would recommend it to anyone wanting to learn about agile software development. One criticism I had of the course (and no training outside of my site is perfect) was that the terms ‘project’ and ‘product’ appeared to be used interchangeably. These words do have very different meanings in my training material, and I am very careful to distinguish between the terms.

A project is a development effort intended to deliver benefit to the customer. A product is an application that is used by the customer in order to achieve that benefit. A project may impact several products in order to achieve that benefit. During business modeling, (the focus of the inception phase) the effort is mostly application independent. The emphasis is on what benefit the development effort will bring to the business. During elaboration requirements are allocated to applications. Construction is focused on products. Transition brings all the work together in order to satisfy the original project requirements. There are 2 testing efforts that occur in an enterprise project;

Product testing to ensure that the products satisfy the individual application requirements.

User acceptance testing to ensure that the enterprise satisfies the requirements of the project.

The following is a diagrams represent a simple enterprise architecture and  how projects can affect this.

                                                                                Figure 1:    Simple Enterprise Architecture

Figure 1: Shows the business includes 4 main areas; HR, Sales, Marketing and Finance. The business makes use of 4 IT products; the Employee Database, A web Analytics application, a Customer Database and a Security application. Some of these products are shared by the business, such as the Customer Database.

Now, assume that a new company wide directive is announced; ‘The company will become SOXv2.2 compliant by the end of the year’. SOX being concerned with security and financing, is going to impact the security application and everything that is dependent upon it.

The SOXv2.2 ‘project’ is born, and each business area identifies the impacts that it has to the way they work. Changes to Human Resources will impact the Employee Database and also the Security application. Changes to Sales will impact the Customer Database and the Security Application. Changes to Marketing impact the Customer Database, Web analytics and Security. Changes to finance impact the Security application.

As you can see, a single company wide project impacts several applications. Not only that, but each application is receiving requirements from several business areas. In addition, there may be other projects in development at the same time that the SOXv2.2 project is announced.

Requirements for each Product are coming from several different projects and requirements for each project are impacting several Products.

I hope to provide some guidelines that will assist with organizing this mess.

2.4    The Maintenance Discipline

RUP describes a method for development that takes iterations of requirements through analysis, design, implementation, testing and deployment; in that sequence. But what happens after the requirements have been developed into production? There is no Maintenance phase to RUP. The RUP says that in order to perform maintenance on requirements that are in production, a new project is started that moves the changes to the requirements through all four phases, Inception, Elaboration, Construction and Transition. If we think of a maintenance project as an iteration (or iterations) of the original project lifecycle, development becomes easier to understand in terms of RUP. In fact if you consider that all work is part of an iteration (forget waterfall) the RUP phases make more sense. Or another way to think of maintenance is that it is just an extension of normal product development; i.e. there is nothing special to maintenance, it is simply a subsequent iteration of normal development.

                                                                                       Figure 2:    Iterations And Releases

The above diagram shows how a maintenance release is treated the same as a development release. The first project creates 2 releases into production, release 1.0 and release 1.1. Prior to a subsequent development release, 2 maintenance efforts are released into production. Every release goes through the 4 RUP phases.

RUP describes guidelines for the activities of each discipline, but it makes no statement about the size effort or time spent in each discipline. It is quite possible that the effort spent in the ‘Inception’ phase of a maintenance release is nothing more than to verify that there is no work to do in this phase.

2.5    The Complete Application

Are your requirements maintained? Do you know what the requirements are for any application in production?

Suppose we ask the same questions about the code that is in production:

Are your code files maintained?

Invariably yes, the code is managed within a software configuration management system that allows checkin, checkout, versioning and merging of code files.

Do you know the versions of the code files that are in production for any application?

I would expect so; otherwise how do you know which files to checkout when changes are needed to the application.

Source code is configuration managed; why not the requirements? You can think of requirements as the same thing as source code, but at a higher level of abstraction. Just like source code, requirements should be; Written, Packaged, Compiled, Tested, Versioned, Configuration Managed and Deployed.

2.5.1     Writing Requirements

Traditionally this is performed using a word processor. The requirements are entered into a document (often named a functional specification, or software requirements specification) as lines of text. Alternatively, a tool developed for capturing requirements may be used, and the requirements entered into the tool.

Modern methods may take a use case approach to writing requirements, where the functional requirements are entered as steps of the use case entered as text. Advanced methods allow capturing of requirements graphically using some type of activity diagram.

Typically, requirements may be documented as lines of text, artifacts of a requirements management tool, steps in a use case or an action in an activity diagram.

2.5.2     Packaging Requirements

Requirements packages are documents, or use cases, or may be individual requirements that are organized into packages within a requirements management tool.

2.5.3      Compiling Requirements

If using a MDA (model driven architecture) approach to developing applications, your requirements might actually be converted to source code automatically by a CASE (computer  aided software environment) tool. In reality I do not know of any organization that is using a MDA approach to developing their applications, but there is no reason why the requirements cannot be modeled.

By realizing use cases as class, state and interaction diagrams, you are half way towards compiling your requirements. Once you have a complete analysis and design model, it’s just a case of putting the model through the right tools in order to generate the software.

2.5.4     Testing Requirements

By ‘test’ I do not mean the act of executing a test case against a requirement. When an analyst analyzes a set of requirements they are checking that the requirements are correct. This is effectively ‘testing’ your requirements. For example, during the realization of a set of use cases with class, state and interaction diagrams most modeling tools will ensure consistency between the different components of the model. You may also be able to execute completeness reports that indicate where a component has been specified, but is not being used.

2.5.5      Versioning Requirements

Addressing the question; Do you know what version of your requirements are in production today?

Like death and taxes, changing requirements are a certainty. If you are using a requirements management tool, the process of versioning changed requirements can be mostly automated. If you are managing your requirements in a document, then version control is going to be a largely manual process. Either way, I am going to assume that the requirements are under version control. Now let’s assume that we are doing iterative development, see Error! Reference source not found.. Our requirements are continuously changing, but the application may already have 2 or more releases into production. If you are using a requirements management tool, you may have the capability to define a baseline of requirements that reflects what went into production for a particular release.

My preference is to take a snapshot (or copy) of the requirements for any particular release and put them into their own read-only project. This is done every time a new release is deployed. Doing this allows the following process to operate.

2.5.6     Configuration Management Of Requirements

Take the situation whereby we have a set of requirements in production and the correct versions of those requirements have been captured in their own read-only project. There is maintenance going on all the time, so subsequent versions of the requirements are currently being worked on. Let us say that version 1.0 of the product is in production and that version 1.1 is being worked on as a maintenance release.

Now take the situation where a new project release has been planned (2.0) which is going to affect a requirement that is currently being worked on maintenance release 1.1. There are 2 versions of the same requirement in existence, that on the maintenance release and that which is in production. Which copy of the requirement is used for project release 2.0?

Answer, (and I know that you got this right) is the requirement that is in production. You do not want to work from the requirement on the maintenance release because it is changing. So, we take another copy of the deployed requirement into the project for release 2.0 and work on it in parallel. It does not matter that there are two version being changed, just like 2 versions of the same code file be being changed at the same time, because when the first version is deployed into production the requirement will be merged with the version 1.0 requirement. It could be either requirement. Whichever gets there first has the relatively simple action of overwriting the 1.0 requirement. The 2nd has to merge their requirement with that which is in production (just like with a source code configuration management process).

Figure 3: contains a diagrammatic representation of this process.

                                                            Figure 3:    Project vs Product Requirements Transfer Process

Initially the project requirements repository is created, to hold the enterprise wide requirements.  As well as impacting several applications, the project and creates a new application. Once the new application is deployed into production, the requirements are checked-in to a ‘read-only’ application requirements repository. The project requirements are archived.

A subsequent project impacts the requirements of the application. Those impacted requirements are checked-out from the application requirements repository and moved into the new project repository. The project modifies the requirements. When the application is in production the requirements are merged with the existing application requirements. The merged requirements are checked-in to the application repository.

In this manner the requirements in the application repository always reflect the requirements of the system in production.

2.6    Requirements Hierarchy

Hierarchy should only be considered within a distinct organization. Do not try to create a hierarchy across domains. For example, Figure 3: shows traceability between the business domain and the IT or system domain. Within each domain there is a hierarchy, but are the business objects at a higher level of abstraction than the IT use cases? (Does the question even make sense?)

Distinguish between the business model and the system model. The way to think of them is that the business model and the system model are not high and low level (parent/child) models, but sit side-by-side. Traceability is almost always from the Business -> (to the) System, but this does not need to imply a hierarchy.

Like a typical company structure, there is a business unit and an IT (systems) unit. The IT department satisfies the needs of the business (and other departments, including themselves), but that does not require us to think of IT as a subservient department to the business.

Consider the following diagram in Figure 3:. To the left is the business. To the right IT. The business contains 'Business Needs'[7] the IT 'System Requirements'. There is no overlap. But there is traceability. The business needs are mapped to system solutions.

Notice that I also show zero overlap between business 'requirement'[8] types and system requirement types. Having the same requirement type in both domains causes a heck of a lot of confusion IME.

2.6.1     Business Needs:

Business processes may or may not, trace to (system) functional requirements (not all business needs are implemented).

Business rules may be implemented by functional or supplementary requirements[9]

2.6.2     System Requirements:

Functional requirements may trace from business needs, but may also come from elsewhere.

Supplementary requirements (in my world) are anything that is not directly captured within a use case, but are restrictions on the functional requirements.

Stakeholder requirements, are system requirements that do not come directly from the business needs. These originate from anyone with a vested interest in the final product and do not need to trace from anywhere (except for an explanation of why they are a good idea).

2.6.3     Levels of Abstraction:

There may be levels of abstraction within each domain model by adding detail to components. For example, a business use case shell may be detailed by adding business objects and roles to the steps of the use case. The 'shell' and the detailed use case are at different levels of abstraction. A system class containing detailed attributes and operation descriptions, may be abstracted (upward) into an object that is captured by a use case.

To summarize, business needs and system requirements are easier to manage if kept independent from each other and treated as 2 distinct domains.

                                                                                           Figure 4:    Separation of Units

2.7    Complexity

I learned the term KISS – Keep It Simple (Stupid, as it was when I first heard the term), a very long time ago when working on military products. During the project this concept was specifically related to the users of our products. The idea being, the users are soldiers. They are not rocket-scientists, and we should bear this in mind when building the user interface and controls.

Since then I have heard the term used in many varied contexts from coding software to documentation. The concept works well for Business Analysts too. We need to consider that our stakeholders do not have the technical know-how that a technical BA has. When talking with the business BAs need to replace the technical gobbledygook with language that our stakeholders can more easily understand.

In the work in the following chapters you will find the examples use the minimum symbolic components that are available to UML, in order to achieve the diagrammatic view of what it is that you are trying to explain. Like RUP, UML tries to offer all tools to all users. I believe that like RUP, users of UML should be making decisions about what they ‘need’ from the UML toolbox prior to using the tools. By that, I do not just mean just which diagrams to use, but also which components on the diagram. For example, some of the activity diagram concepts come from the real-time system modeling world. (Do you really need real-time constraints on a model of an ecommerce website?) Just like using RUP in an agile development environment will strip out many of the tasks around formal reviews, so should you consider which UML components will satisfy your development needs; document these upfront and don’t deviate from your guidelines unless the guidelines need to change.

For example, consider the use case diagram shown in Figure 5:.

                                                                                  Figure 5:    Example Use Case Diagram

This is the use case diagram used in the examples of the subsequent chapters, with a system boundary added. My understanding is (and I have not seen any specification to the contrary), that the use case is always inside the system, whereas actors are always external to the system. If this is true, for all use case diagrams, why has my modeling tool introduced a ‘system boundary’ component into my use case diagram template? What is its purpose, and what does it mean to include an actor ‘inside’ this boundary? Surely, putting an actor inside the boundary would be wrong. Introduction of the ‘system boundary’ to my template appears to serve no purpose and in fact, it is encouraging me to make mistakes (or at the minimum, ambiguous specifications).

So why have all these complex symbolic notations been introduced into UML, if a subset is quite adequate? [To be fair to UML, the governing body does not invent the UML components (at least to the best of my knowledge), they take what is available and formalize it.]

Maybe it is because the users of UML do not see a solution to their problem with the existing language and therefore they introduce new terminology in order to explain what it is that they are trying to model. (Yes, I see this a lot; diagrams containing a textual explanation of what the author means by a symbol, because they did not find the correct way to represent what it is they are trying to model.)

Maybe it is in an effort to save paper, by adding symbols that represent complex constructs, one is able to reduce the size of the diagram.

My take on this goes back to the KISS principal. Using a complex symbol to represent a common pattern that occurs during modeling of system requirements is not helping the stakeholders to understand the system. I try to keep the number of symbol types in my diagrams to a minimum. I don’t expect my stakeholders to understand the difference between an activity that monitors for activity and one that is triggered via an interrupt.

The more variety in the modeling notation, the easier it is for the analyst to use the notation to draw models, but at the same time, the more difficult it is for the stakeholder to understand the model.

The simpler the notation, the more difficult it is for the analyst to model, but the end product is simpler to understand, even if more verbose.

KISS – is a concept for considering your customers, not aimed at the clever techy people.

2.8    Use The Right Tools

Maslow's hammer rule - ‘If the only tool your builder has is a hammer, then everything to them appears as a nail.’

The same concept translated into analysis might be to use the right diagramming tools to document the concept you are trying to describe. If the only UML diagram you are familiar with is the activity diagram (for example), then you are most likely to be tempted to add data to your activity flows in order to explain the information that is manipulated by the requirements. Or sometimes I see GUI screen shots added to use case specifications, in order to explain to user interface to the stakeholder. In my RUP like development process, I use:

·         Activity diagrams, to show the functional sequence of activity as seen by the user.

·         Class diagrams are used to encapsulate data for the system.

·         Use cases are used to explain the steps of a process that give benefit to an actor.

·         Use case storyboards are tools for prototyping the user interface for the system.

Each of these artifacts has their own purpose and audience. If none of these artifacts satisfy your need for a deliverable, then create a new artifact that does, but I don’t recommend using a pre-defined artifact for demonstrating information that it was not intended to.

Or to put it another way, separate the different concerns into the artifacts that are intended to demonstrate those concepts, and don’t put everything onto one deliverable.

2.9    YAGNI

Doing The Simplest Thing Possible That Works (DTSTPTW), is a great principle that has been widely adopted by the Agile community. The questions is: What do you mean by ‘works’?

Another Agile principal is named You Aint Gonna Need It, or YAGNI for short. Great advice as part of the DTSTPTW principal, but who are we referring to when we say ‘you’, and how do you know YAGNI?

My answer to both questions is: ‘Who are you doing this for, and what are they going to do with it?’

Starting with the 2^nd question (which is a sort of subset of the ‘works’ question), the immediate reaction to ‘who is you’, is me. When referring to the person doing the work, the most obvious answer might be that I am doing this because I can’t remember the reasons behind everything I do and therefore I add explanation as to the thinking that went behind the work.

Using the example of ‘you’ being a developer that wrote software in response to discussion with a customer. The developer has working[10] code and knows what it does. But might it not be prudent to capture the conversation they had with the customer?

So we have software documented[11] as source code, and a customer conversation documented in text.

What if the ‘you’ in YAGNI is not specifically referring to the person that did the work? One has to anticipate that the person doing the work, may not be available to explain their thinking behind their work, so should they also consider that the person trying to understand their work, will need a verbose explanation of the their thinking, perhaps supported by diagrams?

Now we add UML diagrams to our documentation, in order to capture the messages being operated on by the software and the architecture of the software.

We now have additional information in the form of sequence diagrams and class, (and possibly state) diagrams with an explanation of why this particular architecture was chosen.

Let’s abstract out some more and suppose that sometime in the future the business process that the software is capturing may change. Perhaps now we need to capture the actual business process independently of its implementation, for the subject matter experts. Afterall, showing a new business person the implementation of a business process, and telling them that’s how it works is not going to explain the reasons behind why the business process is as it was, and why it may have changed.

So now we add use cases to the supporting documentation, to get:

·         Documented source code,

·         Customer conversations,

·         Sequence diagrams,

·         Architecture diagrams,

·         Use cases,

as the artifacts being used to support the working software.

I could go on and discuss the testing and project management needs, but you get the idea. When adopting a YAGNI attitude – where do we stop?

A similar argument applies to the defining ‘Works’ in the DTSTPTW principal. ‘Works for who?’

There is no single answer to these questions; each project needs to define ‘works’ and ‘you’ on its own merits and needs.

The following work attempts to describe what ‘works’ for the business SMEs, Business and System Analysts, Project Managers, Architects and to some extent, testers. If your project needs do not include satisfying all of these needs, then ‘YAGNI’ applies, and you may feel free to ignore artifacts built for those roles.

[The moral here is that 'you' in YAGNI should not be referring to the person doing the work. People in an office do not work for themselves (rarely). When adopting a DTSTPTW principal on project, look outside of your world - if anyone is giving answers to this question, it is the project manager .. ask them what 'works' means.]

2.10Architecture Of The Process

So now you have an insight into the driving forces behind this work; let’s go into how these concepts can be applied to developing and maintaining requirements.

The following chapters will expand upon these ideas and provide various methods for implementing them.

This document assumes that the requirements are managed by the lowest common denomination of tools. In this case I am assuming that the user has access to MS Office (or equivalent documentation tools), as a minimum. Although it may not be explicitly stated, I am assuming that all the procedures described from here on can be performed with MS Word, MS Excel, MS Visio and MS SharePoint.[12]

The following diagram, Figure 5: gives a brief overview of how the Office applications may be used during the requirements process.

                                                                                       Figure 6:    Configuration Of Tools

2.10.1  Tools

MS Word – will be used to manage requirements through documents.

MS Excel - is used to manage a glossary of terms for the project or product.

MS Visio – is used for modeling the requirements.

MOSS – is used to control the documents that contain the requirements.

2.10.2  Relationships

Terms in the glossary will be referenced from the requirements documents.

Documents from Word will be controlled in MOSS.

Model files from Visio will be controlled by MOSS.

Requirements in Word documents are modeled in Visio.

Diagrams from Visio models become embedded in requirements documents.

2.11Summary

I hope that this chapter explained the basic concepts behind my experiences with requirements analysis and modeling. In summary the guidelines are:

·         Ad-hoc vs Predefined Process – Remember, software development is not a work of art. A work of art is intended to be a unique and original display of human creativity - generally architected, designed and built by a single person. In contrast, software should be designed to be replicable, re-usable and is worked on by many different people with different skill-sets.

·         Ambiguity – Clearly define any terms or notations that are open to interpretation.

·         Consistency – Always work from a template. If the template does not exist, create one and have it approved by the appropriate audience.

·         Duplication – Don’t duplicate! Wherever possible maintain a single copy in a single location and reference the item.

·         Iterative Development – You don’t try to eat a chocolate bar by stuffing it into your mouth whole. Instead you bite off little chunks and devour them separately. Similarly with development; break the problem into pieces, organize and prioritize the pieces into manageable chunks, and work on each as its own smaller problem.

·         Keep It Simple – Remember who your audience is and produce to their understanding.

·         Organization – Don’t throw everything into a repository bucket and expect your audience to be able to sift through those items in order to locate what they need. Only show the your stakeholders what it is they need to see.

·         Plan - Before you start, plan what it is that you intend to do. Set a date for completion and estimate how much effort and resources it is going to take.

·         Requirements – Are another form of software, but at a higher level of abstraction than code. They should be developed with the same level control as you would your code.

·         Responsibility – Define a clear separation of responsibilities between business, systems, project management and product management.

·         YAGNI – Don’t do anything until you know who wants it, and what they are going to do with it.