Seilevel
Seilevel Home
Back to Blog Home - Requirements Defined

Monday, February 15, 2010

Software Requirements Specification Template

We’ve just updated our suggested business requirements document template, though it can be used as a template for any type of requirements specification. You can find it here on our Resources page. One thing we strongly suggest is that you create and update requirements within a requirements management tool and then output as needed to a document such as this. We use Borland Caliber and have found that it is relatively easy to export from Caliber into this format. This is a great way to deliver your requirements to the team, but if you can avoid it, do not use the Word document as your source as you will likely step on each other eventually and it makes traceability very hard!

Labels: , ,

Requirements Defined Newsletter Bookmark and Share

Wednesday, January 27, 2010

Managing the Software Requirements Process for “Green Screen” Replacement Applications – Part 1

I have been on teams that created requirements for replacing old “Green Screen” mainframe applications and have also observed the work of my colleagues on similar projects. The observations here are based on our experiences with these efforts and offer suggestions to anyone who is about to embark on a similar project.

This post is split into two parts. Part 1 identifies issues that make these projects challenging and different from other requirements projects. Part 2 offers specific suggestions on how to tackle these projects and describes practices that will result in a greater likelihood of success.

What makes Green Screen replacement projects so challenging?

It is not a lack of proper tools or models that make these requirements difficult to capture and define. The complexities are rooted in the following:
a. Existing organizational processes
b. Resistance to change due to fear and uncertainty
c. Disruption to current operations
d. Potential job losses
e. Lack of clear understanding of the impact on indirect users of the existing system
f. Poor vendor communications to the rank and file users of the new system
g. Lack of proper management communications on the value of the proposed change
The combination of these factors makes the act of eliciting good requirements difficult and extremely challenging. Each of these areas is discussed in greater detail below.


Existing Organizational Processes

Green Screen applications are typically twenty or thirty years old, though it is not unusual to find applications that have been in use for longer periods of time. Over this time, extremely elaborate organizational processes will have been created, evolved, perfected and institutionalized in the company. Changing these longstanding processes to support a new application can be extremely difficult. While it can be argued that any kind of application change is likely to confront process change, four things made Green Screen processes unique.

a. Longstanding
The processes built around Green Screen applications will be as old as the applications themselves. Change is inherently difficult. Changing something that has been around for a quarter century or more is infinitely more difficult.


b. Stable
For the most part, these processes will have undergone little substantive change for many years. Most recent changes would have been tweaking to make something more efficient, plug a few holes, fix weaknesses in the existing workflow or in response to some minor changes in the business environment. These processes are not perfect but they keep the show going day in and day out.


c. Fully Integrated with the Application
The existing processes and the application will have a seamless linkage. No matter how convoluted and byzantine the processes might be, they are totally synchronized with the application. Over time, the organization will have developed detailed processes that reinforce the strengths of the application and compensate for the weaknesses. In a perverse way, changing these processes is tinkering with perfection or something that looks awfully close to it when it comes to marrying an application with supporting processes.


d. Fully Understood

The combination of longevity, stability and application integration make the processes extremely well understood within the company. For the most part, all the different departments and individuals within these departments know what they need to do, when they need to do it and how to do it. Replacing all this with new processes that no one fully understands is an extremely challenging proposition.


Resistance to Change Due To Fear and Uncertainty

This a common characteristic of many projects that seek to introduce a new application or a new way of doing things. In the case of Green Screen applications, this natural resistance is hardened for the following reasons.

a. Fear of Failure on a Massive Scale

Green Screen applications are usually “mission critical.” They typically are extremely important to the day to day running of the business. Any failure during the switchover will have an immediate and tangible financial impact on the business that will be reflected in quarterly earnings. Depending on the reach of the application, the impact could be companywide with potentially disastrous consequences. This reality adds an extra edge to the element of fear associated with the change.


b. Uncertainty Due to a Major Systemic Change

Almost all Green Screen applications involve changes in multiple departments or functional areas of the company. It is not uncommon for the entire operations of a company to be impacted by a Green Screen change. Whenever multiple departments are involved, the element of uncertainty associated with the change gets ratcheted up. These efforts are almost always accompanied by an enormous amount of chatter, rumors and conflicting statements about who is doing or not doing something. Every day will bring a new dynamic because some department or the other is unhappy, not going to support the rollout fully or flat out not going to make a change. This leads to an enormous amount of confusion that brings with it a great amount of uncertainty.


c. Let the Other Guy Go First

In such an environment where fear and uncertainty are pervasive, the smart play is to do nothing and wait for the next guy, department or functional group to make the first move. So, you will meet with a lot of covert and passive resistance to change that needs to be managed.


d. Incomplete Plans

The sheer complexity and scope of Green Screen change efforts makes thorough planning of the changeover practically impossible. It is not possible to have fully fleshed out responses to all the legitimate concerns that users will have around the change. This gives the impression of an effort that is not carefully thought through. It is natural for users to focus on the unknowns and areas of weakness in the planning and extrapolate that to the entire effort. These perceptions feed into the underlying fear and add to the uncertainty barrier to be overcome.


Disruption to Current Operations

Most Green Screen systems are transactional systems on which the daily business of the company is conducted. When the switch over takes place there will be a transition period during which some amount of productivity will be lost as people get used to the new system. This is true even for successful implementations. It takes the users a few weeks to a couple of quarters to truly understand the new features and appreciate the benefits. This perceived (and real) loss of productivity even in a best case scenario causes users to instinctively resist or at the very least postpone the day of reckoning by throwing up roadblocks to the entire process starting with requirements. This resistance to the requirements effort is manifested in the following ways.

a. Why is My Department Being Penalized?
This complaint will almost certainly come from departments that perform data entry. In a vast majority of situations, Green Screen data entry is faster than mouse driven data entry that it is usually replaced with. This will lead to a drop in productivity in the short run for the department performing data entry. But it is not a zero sum game. These increases in time to perform some tasks are almost always offset by significant benefits in other areas of the application like the ability to cross sell or up sell customers. But it usually takes some time for these benefits to be realized. The increases in time and resultant productivity losses however are felt immediately. It is these short term losses that functional area managers will focus on. These arguments will be framed as having their departments victimized so that other departments can do their jobs better.

b. My Numbers Will Look Bad
Organizations that have extensive productivity measurement systems in place that track time very closely will react very strongly to anything that causes a short term hit in productivity or the time it takes to perform certain tasks. This is a very real problem that the requirements engineer will face. There will be outright hostility and lack of cooperation as a result of this that needs to be managed and eventually overcome if any progress is to be made.


Potential Job Losses

The anticipation of the loss of jobs causes both direct and indirect opposition to the requirements efforts of the replacement application. There are two main areas where jobs typically become redundant when Green Screen systems are replaced.

a. Data Entry Operators
Green Screen systems typically have highly specialized data entry personnel. The lack of graphical interfaces results in reliance on arcane Function Key combinations to perform simple and complex data entry tasks. Most companies have teams of employees who have mastered these tasks and are a valuable part of the daily operations. When the new application is introduced many, if not all of these employees will no longer needed by the company and are likely to be let go.
These employees are often treated as expendable by their companies but they are a treasure trove of information for a requirements engineer. They understand the underlying application better than anyone else in the organization. Simply put, they can tell you what the application actually does as opposed to what someone thinks it does or should be doing. This information is critical since Green Screen applications typically have very poor or no documentation of their functionality.
They know who they perform data entry for in addition to the obvious users. These are the hidden users of the system who need to be accounted for and are often overlooked with potentially dangerous consequences down the road.
Last and most importantly, they can tell you “why” some things are done. This is critically important to understand what exactly a system does and needs to be replicated by the replacement. Simply playing with an application and going through it from end to end is not sufficient to understand what the system is doing. This is especially true if you are not familiar with the intricacies of the application.
In a nutshell, these users are very critical to understanding what the existing system does, why it does certain things and who are the users of the system. But faced with the prospect of almost certainly losing their jobs if the new effort is successful, they have no incentive to cooperate. Not having the information in their heads can have very serious consequences for the requirements created to support the changeover.


b. Employees Involved in Manual Processing of Information

A generalization of Green Screen systems is that they are excellent at transaction processing but very poor at data analysis. Over the years organizations have addressed this gap by developing complex data analysis solutions based on third party applictions. But even with these extensive investments, there are always gaps in the data needed to make routine business decisions. These gaps are invariably filled with data extracts to spreadsheets that are analyzed by specialists. The data aggregation into spreadsheets is done by employees who perform time consuming tasks to import data from multiple sources into a single spreadsheet that is then forwarded on the specialist for interpretation and decision making.
This aggregation and analysis of data outside the main system are usually referred to as “manual” processes by most companies. These processes are extremely difficult to understand or infer from a walkthrough of the application. Even assuming that we can guess at a missing process, without an in depth knowledge of all the systems, it is extremely difficult to know where the data to make the analysis comes from, how it is aggregated and cleaned up before being provided for analysis and decision making.
This information is in the heads of users who perform these tasks. Here again, the reality that they could all be out of a job if the replacement effort is successful leads to resistance and lack of cooperation with the requirements effort.


Not Understanding the Impact on All Users

The universe of users impacted by a system change is not limited to users who directly interact with the system. This is true of all systems and a common mistake made in many requirements efforts. However, the sheer scale and scope of most Green Screen replacements compounds this problem.

For example, an application that replaces a Green Screen Order Entry system impacts far more than just the Sales Team who are the direct users of the application. Accounting, Finance, Customer Service, Post Order Processing, Marketing and Product Management will all be impacted either directly or indirectly by the change. Each of these departments interacts with the system in one of four ways:
a. Directly – Customer Service is likely to use the system to enter Orders to process returns and repairs.
b. Data Providers – Product Management will provide data that is used by the Order Entry system.
c. Data Consumers – Post Order Processing will use data created by the Order Entry system for their operations.
d. Data Providers AND Consumers – Accounting, Marketing and Finance will typically provide data and inputs that are used by the system and also consume data generated by the system.

Not knowing who all the impacted users are and how they interface with the system is a critical mistake that can potentially torpedo a requirements effort.


Poor Vendor Communications

While some organizations do develop new applications from the ground up to replace Green Screen applications, most companies use off the shelf software that is customized for the specific needs of their business. I have yet to see one instance where the features and benefits of the new software have been clearly communicated to the user community.

The vendors are very heavily engaged with senior management and a select group of users during the sales process. Once the sale is made, the technical staff come in and start the process of implementing the solution. I have not seen a coherent strategy in place from any vendor to actively evangelize their product and its benefits to users AFTER the sale is made and BEFORE the software goes live. This leaves a huge vacuum of knowledge and expectations in the user community. It is in this vacuum that fear and uncertainty take root and blossom into full blown chaos.

Specifically, these are the key areas of deficiency that lead to problems.

a. The Built in Processes Supported by the Product and Recommended by the Vendor
All vendors of enterprise class software claim to have “best practices and processes” built into their software. But I am yet to see any kind of documentation, presentation, training or coherent communications that explain clearly and simply to users what these processes are and how they should be adopted. If there are such materials and resources available, then they sure fooled me with totally inscrutable presentations that were so stealthy that I missed them altogether!

As requirements professionals we are constantly questioned by users as to what these processes and practices are. The fact that we have to confess total ignorance hurts us in two ways. First, it hurts our credibility with users who are bemused that we do not seem to know anything about the system we are de-facto representatives of. Second, users are reluctant to spend a lot of time defining processes and procedures that may all be overridden by processes that are to be adopted with the new software implementation.


b. The Features and Benefits of the New System

The situation faced with lack of information about the processes to be adopted with the new system are true of the features as well. Most of the time users are given a dog and pony show where someone does a quick fly through of the application. These are at a very high level and of little use to the user community who have much more specific questions in mind that are not answered. I have seen two things happen and both are bad.

First, users assume that the software has certain capabilities and features that it may or may not have. These assumptions are seldom articulated until we are well past requirements gathering and moving towards implementation. This makes for a whole bunch of nasty surprises.
Second, users lose the forest for the trees. I have seen quite a few demonstrations that very quickly get into the weeds on some arcane point a strident user or user group make. Before you know it, the demonstration has degenerated into an agonizing exercise in specificity that only one or a small handful of users and the demonstrator care about. Most importantly, huge chunks of precious demonstration time are lost and the remaining time makes the rest of the demonstration a waste of everyone’s time since they are rushed and general in the extreme.

c. The Inevitability Fallacy
Vendors assume that since the sale is made, it is inevitable that the system will get implemented and adopted by the user community. This belief guides their interactions with the user community. Unfortunately, most vendors do not realize that just because someone signed a contract to purchase the software, there is no guarantee that the rest of the organization will simply go along with the decision. They usually come to this frightening realization many months into the implementation effort when they do not seem to be getting the traction they thought they would be getting. The requirements effort is a good predictor of potential issues down the road. General rule of thumb – if the requirements team is competent and unable to generate good requirements, it usually means that the users are not buying whatever it is the vendors are trying to sell them.


Lack of Proper Management Communications to Users on the Value of the Proposed Change

There is a lack of clear, concise communications from Management and Project Sponsors on what the business value of the proposed change is, how the business value is to be realized as a result of the change, over what time frame the value will be realized, how it will impact the business in the short and long run and who will be impacted by the change.

What I have seen in practice are conflicting statements of value (both real and imaginary), extremely general statements of benefits (we need to come into the 21st century), vague notions around the reason for the change (it is about time we did something different around here), extremely aggressive and unrealistic timelines (we will go live in 3 months where 12 months is more reasonable) and little to no information at all on the things that the users care about the most – how will this affect me, my job, my department and my coworkers.

Presented with this vacuum, users fill in the blanks with their own combination of fear, rumors, disbelief, derision and a combination of outright and latent hostility. For a requirements engineer, this translates into many hours and days of wasted effort in getting people to meetings they do not want to attend, and when they do get there, trying to answer fundamental questions about the project – why, how much, when, so what – BEFORE you can even begin to elicit one useful requirement out of the group. I have often found myself in the uncomfortable position of not knowing the answers to their questions or, worse yet, knowing the answers and wondering if I should be the one giving it to the users.

Great, Now What?
As you read this, you might feel like you are in an echo chamber. Anyone who has practiced our craft long enough is very familiar with everything I have commented on here. It has gotten to the point where we are resigned to dealing with these kinds of situations and just “accepting” it as the reality we are confronted with.

But it need not and should not be this way. Change is inherent in every business endeavor. We just need to do a better job of managing it. There are ways in which we can manage the process of change with common sense, honest and open communication and dignity. This does not mean that the end result will be satisfactory for all or that there will be no pain involved. The people we work with are far smarter than we give them credit for. They may not like change but are more likely to help everyone get there if we all know what we are striving for.

In my next post on this topic, I will discuss specific steps that can be taken to overcome the hurdles identified in this post and answer the question I posited “Great, Now What?”

Labels: , , ,

Requirements Defined Newsletter Bookmark and Share

Tuesday, November 25, 2008

Webinar Update: How To Successfully Manage Software Requirements In A Global Organization

We've been getting quite a few requests for our most recent webinar. I thought that I would make it available for the folks who missed it.

We'd love to get your feedback, so please post your comments below. Also please feel free to share the slidecast with your friends and colleagues.



Labels: ,

Requirements Defined Newsletter Bookmark and Share

3 Big CaliberRM Gotchas And How To Fix Them Part 1

So we have been using Caliber RM for awhile now. Joy Beatty wrote about our selection process in a prior blog post. Since that time we have gotten some more experience and overall we are very happy with our choice of CaliberRM. However no tool in life is perfect and we are analysts afterall, so rather than post all the things we love about CaliberRM, here are some gotchas that we have found when using it.

Since we had a lot of projects in progress, one of the first tasks was to import a lot of docs into CaliberRM. It turns out that the import tool has a tough time, unless the document is very structured and makes extensive use of styles, so we ended up doing the imports by hand. These gotchas apply regardless.


Drag And Drop


Moving requirements around doesn't work quite right with drag and drop. You will find that sometimes no matter how hard you try it is incredibly difficult to move a requirement to the top of the list. It will either drop to the level above or you will drag the wrong requirement even though you definitely grabbed the correct one.

The key is to click the folder to move and wait a second, then when you move it make sure it is the right folder. The target position will be indicated by a line between folders, however that doesn't work if you are dragging a folder to the top position of a subfolder. Sometimes it was easier to just drag folders to the second position, then drag the first folder to the correct position.


You Can Only Paste Images

If you try to paste something that isn't an image (OLE object) it will show up as dead in CaliberRM as a tiny rectangle with an X inside. I will typically be gutsy and paste a whole section then go look to see how bad it looks. I will fix any images by hand.


a) If you did custom drawing in visio the easiest way to get them in is to cut the visio diagram and then paste special back into word as a bitmap. You can then copy the bitmap into caliber

b) If you did custom drawing in word itself it is VERY difficult to get in because you can’t copy and paste all the shapes into their relative positions. Direct drawing in word is by far the worst thing I encountered. I had to print the page to Snagit (screen capture/editing program) and then cut and paste out of Snagit into caliber.

c) Sometimes some images in word docs aren’t truly images but they aren’t Visio pastes. Just copy and paste as a bitmap.

d) Sometimes the object is an OLE object that when you paste as a bitmap the color scheme changes to an inverted color map. In those cases, pasting into MSPaint first helped. MSPaint proved to be the most reliable source for pasting images.

e) Sometimes CaliberRM will get into a weird state where it will paste the last image you pasted vs. the one that is in the clipboard. Restart caliber.


f) Sometimes CaliberRM will show you that you pasted the images but after you save they will all be gone. Restart caliber.


g) Sometimes CaliberRM will resize your image in a funny way. You can resize it back to the approximate shape. We believe that typically happens when you have an image embedded in a table. If you are able to find the frame of the cell sometimes you can delete it and paste the image outside of the table and it will size properly.


h) To delete an image in caliber you have to right click it and select delete. The usual paradigm of selecting and delete button doesn’t work

Tables Can Be Too Big

Some tables have a large amount of html and so a medium size table will actually exceed the 200,000 character limit of the fields. Turn change tracking off, remove formatting and pasting into excel first can all help. Pasting into excel took a 400k character table down to 200K and it looked exactly the same.

Stay tuned for Part 2, where I'll cover 5 more CaliberRM gotchas.

Labels: , , , ,

Requirements Defined Newsletter Bookmark and Share

Wednesday, November 19, 2008

Why Do We Model Software Requirements?

The other day, I was flying to California to visit my customer. On the plane, I was seated next to a gentleman who worked for a small engineering firm in the Silicon Valley.


We quickly struck up a conversation about work and when I began to explain what I do), he got this perplexed look on his face. Seeing the confused look, I decided to try and explain in greater detail what I do as a product manager.

The gentleman quickly explained that he understood the idea of requirements but did not see how there would be enough demand for someone to do this for a living. Then he said "So, tell me what your company does that is so different from what I might do."

I briefly began telling him about requirement work and when I got to modeling he just laughed. "How and why do you model a requirement?” he chuckled. “A requirement is just a statement that says what functions you want the software to do.


I compared Use cases to an assembly instruction for one of his mechanical devices, and an ERD to an exploded view of one of the fully assembled parts that he might design. We discussed benefits of modeling in opposition to just creating a lot of "System Shall" statements.

I summarized things this way:


Requirements Models Allow Us to Organize Our Data in Multiple Ways.

There are only so many ways to say that someone needs a log in screen. But who needs it? And why?


By placing information into models, such as context diagrams or organizational charts, we can see information from angles that we wouldn’t normally have. We can use the images to gain perspective that we wouldn’t normally have.


Models Help Us to See Things That Might Be Missing.

When you’re sitting down with someone, it’s pretty easy for them to take a first stab at telling you everything they want.


But how many times have you had someone say, “Yep, that’s it,” when you asked them if you’ve covered everything only to find out that that there were, in fact, a few pieces missing.


Putting things down on paper helps us arrange information visually so that we can see the gaps that we normally wouldn’t see in a long list of requirements.


Models Create a Visual Representation of What’s Expected.

Ever tried to describe a web page without building a wireframe?


You’ve probably discovered by now that even if you scratch out a design on piece of paper and hand it to someone it’s more effective than writing 1000 words.


Plus when you put a wireframe in front of your customer, you can get them to say, “Yep, that’s what I was looking for,” or “Nope. That’s not it.” In either case, you’re able to get their feedback on something solid before you give it to development.


As we continued talking, I saw the light go on.


Models aren’t just fancy drawings that product managers use to eat up time and paper. They are an effective and powerful tool that helps us communicate with our users and developers. Don’t get me wrong, you need to be able to write up functional specifications clearly and concisely.


But do yourself a favor. Add a few models to your toolkit.

Labels: , , ,

Requirements Defined Newsletter Bookmark and Share