The Career Programmer: Guerilla Tactics For An Imperfect World - Chapter 5

Author Christopher Duncan Title The Career Programmer: Guerilla Tactics For An Imperfect World Publisher APress Published Jan 2002 ISBN 1590590082 Price US 29.95 Pages 240

Chapter 5 - Getting Your Requirements Etched in Stone

The Curse of the Casual Requirement is a classic thriller guaranteed to scare the pants off of programmers everywhere. It’s a bit of a sleeper, though, as the scary stuff doesn’t happen in the beginning. Unlike most mysteries with the good guys winning in the end and the blame falling on the butler, in our little story the good guys lose and they never really could afford a butler to begin with. The software development process begins with an idea for a program. This idea is typically about as fuzzy as those socks that get lost behind the washing machine. When the programmers first get wind of management’s desire for new software, only two paths can be taken. The first is the default direction, in which the programmers do nothing and begin designing or coding based on whatever nebulous requirements they were given. The second direction is more arduous: the programmers must fight, scratch, and claw for every single detail that they can get and make sure it’s documented in explicit and unwavering language for posterity. In other words, this entails getting the specifics and generating a paper trail to be used at the end of the project, or at any other point in which the developers need to defend themselves.

If you already follow an organized, structured, and effective requirements-gathering process, you don’t need guerilla tactics. Instead, you should probably spend more time hanging out in the coffee shops that programmers frequent, as you’re sure to get the local hero treatment. For the rest of us, trying to get management to cough up the details and commit to them in any form more tangible than the spoken word is harder than trying to herd a corral full of greased pigs into a room for a bath. And, no, I’m not going to draw any further parallels. My own management may be reading this, and I’ve grown rather fond of my paychecks arriving on a regular basis.

Make no mistake: if you leave room for people to wiggle on the interpretation of a requirement at some future point in time, they will. At the very last minute. Furthermore, an imprecisely worded requirement is an open invitation for scope creep. Even if you do everything right from this point onwards, either of these can throw you into a frenzy of overtime when you’re one week away from the deadline. The requirements will suddenly change, and of course your deadline won’t. You might be tempted to argue that you were hired to write software, not manage the company, and so therefore it’s not your job to make the requirements specific. The requirements should be that way when they come to you, and whoever wants the program has the responsibility of making this so. In terms of the world I’d like to live in, you certainly won’t get any arguments from me. However, it’s also a well-documented fact that the world I’d like to live in entails much more money, offices with real walls, and the complete absence of middle management by federal decree, just to list the ones that can be printed. In the world that we step into each day to do our jobs, things work a little differently. Because we’re at the bottom of the food chain, we rarely have the luxury of demanding much of anything. And, because the requirements for the software we write comes from those who outrank us, we typically receive them in a wide variety of forms, with none of them organized and very few of them detailed. Consequently, it is in fact our job to make sure that the requirements are explicit and well documented before we begin our design. It simply won’t happen otherwise, and we are the ones who will ultimately pay the price at the end of the show. Where’s a good butler when you need one?

You Don ’t Have to Like It. It Just Has to Be Clear.

Another thing that should be considered at this point is that, even though we tend to get a little possessive about our programs once we start working on them, when it comes to requirements it doesn’t matter if we like them or not. The only thing that matters is that they are precise and unwavering. Whether you’re a mercenary or a full-time employee, you’re a hired gun in management’s eyes: they brought you on board to write the software that they needed or wanted and your job exists for no other reason.

I worked for one company that tasked my group with writing a database system to manage customer information. As this was a national firm, part of our requirement was to keep the data up to date in thirty cities. The decision was made at a higher level that this should be done with a replicated database with each city having a copy of the data. When any one city would update information, databases in all other cities were to be instantaneously updated via the corporate WAN. We implemented this system and delivered it, on time and under budget. It was at this approximate point in time that Internet became a household word, which of course meant that it was one of those trendy things that middle management felt we should be using. Therefore, mere weeks after we finished installing the system that they asked for in thirty cities, the word came down to us that all the data should reside on one computer at a single location and access should be provided to the thirty cities via a Web browser interface. Consequently, the system that was now installed and serving its purpose was to be thrown away and completely rewritten from the ground up to provide the exact same functionality. I don’t count beans for a living (unless you want to include coffee in that equation), so I have no idea how much money they threw out the window on this project. But it makes me feel a little better about all those flying monitors.

We should note a couple of important points from this example. First of all, it’s obviously incredibly wasteful to implement a system, field it, train the users in its operation, and then immediately scrap it just to do the exact same thing on a different platform (and for no other reason than to be trendy). However, that’s not my problem. I’m hired to write software, not manage companies. Furthermore, if they want to pay me twice to write the same system, my bank makes little distinction when it comes to the deposits. In other words, because it’s not my company, choosing which programs to implement or what their requirements should be is not for me to say. If I feel strongly about the matter, I need to quit and start a company of my own. Otherwise, it’s my duty to implement the decisions of the people who hired me.

That being said, the second thing to note here is that the amount of money this company wasted was probably enough to keep me on a beach with a full margarita glass for a good year or two. The reason this money was pointlessly spent was due to a fundamental mistake in the requirements process. In the very beginning, before a programmer had even heard of the project, they were specifying how it should be done, when the requirements phase is about what, not how. They threw suitcases of money out the window simply to change how something was done when the business needs had already been met. Unfortunately, the evening that the money went flying out the window the night watchman and his partner were on vacation, which is truly a shame. It might have paid for all that therapy.

If you want to spend your time coding a system that inspires you personally, you may have to hang out a shingle and go into business for yourself. I’ve been asked to write a lot of things that I didn’t find particularly riveting. I can live with that. All I ask is that, if you’re going to bore me to tears, please go about it in a very precise manner. If you’d like for me to write your system twice, that’s just fine with me as long as the second iteration is just as explicit as the first. I will give these folks credit for one thing: they had no idea what they were doing, but they could explain that to you in great detail.

Where Does the Power Lie?

Regardless of how much sense it makes to implement a particular software system, when it gets to our desks the question is not “why should we write it?” but rather “what exactly should we write?” If we can get satisfactory answers to the latter, preferably in writing, then we’ve got a fighting chance at meeting the deadlines that will eventually await us. The first step to take in getting these requirements nailed down may seem like an exercise in the obvious unless you’ve been wandering the halls of Corporate America for a while. As programmers, we are not in a position to declare that a piece of software is complete. Rather, someone above us in the food chain must sign off on the system and call it done. Who is the person who has that authority? Is it one person, or is it some formal or informal consortium that must be satisfied before we can put the code, and ourselves, to bed? In short, who makes the decisions?

Until we have identified this person or group, we don’t know who to turn to both at the end of the project when we’re done and in the very beginning when we want to get the requirements etched in stone. It’s a common mistake to assume that, if our boss comes to us and tells us to write a program, then he must be the decision maker. I can assure you, particularly if he’s middle management, that he has about as much authority over the definition of the project as you do. If you put your fate in his hands when it comes to the requirements phase, you may as well stock up on espresso. You’re going to need it. The way it typically works in any company large enough to have a layer of middle management is that people positioned above your boss are the ones who truly need to be satisfied with the programs you write. Chances are good that the manager you directly report to is not a programmer. Consequently, he has neither the training nor the motivation to press his managers for more detail on a project. In fact, he’s likely to avoid just that sort of thing, as people who make too much noise in the business world are often put on the slow track when it comes to promotions.

If you work in a smaller company, you may not have much middle management to deal with. This doesn’t mean, however, that the person who asks you to write the program is the only one who needs to be satisfied when the coding is done. People from other departments may be involved. If you work in a vertical market, there may well be important customers who have a say as well. Basically, anyone who wants to put their finger in the pie and has enough political clout to gain entry to the game must be taken into consideration. No matter what your company’s structure, when the word comes down to your team that there’s a program to write, the very first and most crucial step to take is to quickly and accurately identify who the people are who have the final decision-making authority over your system. Once again, you may be tempted to shrug this duty off to your project manager and turn back to your compiler. However, you must bear in mind that you’re on a team. In our business, the fate suffered by one is shared by all. If your project manager is stressed out and living in overtime city, it’s a pretty safe bet that you will be, too. One of the nice things about working on a team, though, is that you have more people to apply to a task. This will come in handy, because identifying the major players can require a bit of detective work and you won’t have much time to figure it out.

Know up front that there are times in our business when you must make a choice between taking action that involves some political risk or suffering the consequences that are sure to befall your project if you don’t. If there were a simple prescribed set of rules that every company recognized that would allow you to operate within your normal chain of command and accomplish all that you need to deliver your software, you wouldn’t face this dilemma. These rules don’t exist. If you’re a good boy, you’ll trust those above you in the food chain and simply do what you’re told by your immediate superior. You probably won’t get yelled at much, I’ll grant you. However, if one path offers a little political risk, the other guarantees the evils that we suffer on every release. I decided long ago that I’ve had enough of pointlessly chaotic releases.

Politics Are an Inescapable Reality

In fact, I also made a decision about politics in general many years ago. I used to have a philosophy that many programmers share: I just wasn’t going to get involved in any of that political nonsense. I was a programmer, I was there to code, and, if everyone else wanted to stand around the water cooler and play little power games, then fine. I had serious work to do. I eventually ended up in a small company on a project that required only a couple of programmers. My project manager, who was the head of development, was actually a solid database programmer. So solid, in fact, that he kept his head buried in a database and actively avoided any project management duties.

The programmer initially assigned to this project was a sharp guy, but he was one guy too few for the deadline that was dictated. The manager was pressed to beef up the team a little, and I wanted on the project. It was technology I wanted to play with, and I liked the guy that was already on it. However, a new guy who didn’t have even the most fundamental grasp of the programming language itself, let alone the technologies, was available. Not to be uncharitable, but let’s just say that no amount of experience was every going to make this guy a good programmer. Some folks have it, and some don’t. Nonetheless, having to deal with the issue at all was a distraction that kept the manager from enjoying his database programming, so the new guy was quickly assigned to the team so that he could return to his fun.

Naturally, the project’s progress deteriorated rapidly as the original coder had to not only do his own job but baby-sit the new guy and clean up after him as well. Several weeks went by, and the manager was pressed to get the project back on track. Obviously, the solution was more bodies. This time, due in no small part to the lobbying effort of the lead programmer, I was assigned. We decided that the first thing that needed to be done was to lighten our load by one body so that we could get some work done. I was a very vocal person, and the lead programmer was much more politically savvy. So, I confronted the manager without so much as the slightest regard for diplomacy and had the guy reassigned to the equivalent of scraping gum off the bottom of chairs. In retrospect, I may have made some comments about how stupid it was to have assigned this clown in the first place. I was also rather forceful and demanding, because we were already working overtime and this guy was making matters worse rather than better. As I said, I wasn’t interested in politics and I saw it as a simple, cut-and-dried technical matter. This wasn’t a particularly bright thing for me to do, but I didn’t realize it at the time.

In the end, we delivered the project two weeks late after many all-nighters. That’s not on time and under budget. However, in our business, being two weeks late is also a little better than the average. Nonetheless, when it was all completed, I suddenly found myself in the manager’s office. By the time I got back to my cube from the conversation, my network login and my job were both history. The stated reason was because the program was late, but curiously only one of the two programmers was fired. The truth of the matter was much more simple: I ticked off the wrong guy, and I paid for it.

Incredulous, particularly after I had just killed myself with overtime in the name of being a dedicated employee, I went to one of the company owners. He was a good guy, and just told it like it was. He agreed that the situation was bogus but pointed out that my manager was the head of development and, unless there was an extremely compelling reason to override him, he had to back him up. He then told me something that lives with me to this day. He said that I knew as well as he that, while technically I was being treated unfairly, politics were just as real and valid a consideration in business as any other aspect. He was half right. What he said about politics was true, but I didn’t know that at the time. I decided then and there that although in the future I may lose political battles from time to time, I would never, ever again lose because I didn’t play.

The lead programmer, who had much more common sense than I, continued to rise in the company. He’s still a friend to this day, and he continues to do well in the programming business due to the unbeatable combination of good technical abilities and good political skills. And, although I certainly haven’t won every battle I’ve fought, I have never again ignored political realities.

The example I’ve just given has nothing to do with defining the requirements for a software project. However, it has everything to do with how you get them. As we were considering, chances are good that the people who must be satisfied before you can stop coding and get some sleep are further up the food chain than your immediate manager. This poses a dilemma. If you go over your manager’s head, you risk ticking off the person who can eliminate your source of income. On the other hand, if you don’t, you’re not going to have any time to spend your money anyway as you’ll always be at the office coding away to ever-changing requirements. We’ll discuss some ways to communicate directly with the decisions makers in a moment. For now, it’s sufficient to say that our first step is to identify the people who truly have sign-off power on the software. Between you, your fellow programmers, and a bit of asking around, you’ll find it’s usually not that hard to figure out once you decide to look.

Identifying the Other Influential People

Having made note of where the power lies, the next thing to jot down is less of a political issue and more of a practical one. Any system is going to have some domain experts, that is, those people who have the business experience relevant to the system being developed. For instance, one of the projects I’ve worked on involved software for air traffic control. A couple of the guys at the office used to work as controllers, and they were considered domain experts because they had worked the position and knew what a controller needed out of software. It’s important to know which domain experts will be involved in defining the requirements of your system because these people bring a very practical perspective to the software you will develop. In the end, people will use your program to accomplish a set of goals. The more input you can get from domain experts, the better your software will be. It’s also worth mentioning that these people typically have some degree of political clout, or management wouldn’t have let them participate in defining the software to begin with.

If it’s possible for the type of work you’re doing, it’s also a good idea to list some actual users as well, the real people who will be using the system. They often have a perspective that’s very different from anyone else, and they can also help you clarify the requirements. It’s better to hear their voice now than to wait until the software is fielded, they don’t like it, and you find yourself redesigning the thing in the beta testing phase of the project. It happens.

I realize that I often paint a picture of Corporate America as a place in which common sense is never a priority and people are always scheming, unreasonable, or just plain hard to work with. Although this is the case often enough to make it foolish to ignore, a great many programmers live in an environment that’s more accurately a combination of this sort of nonsense and groups of smart, practical, and dedicated people. If I emphasize the bizarre aspect of the business world, it’s only to make you realize that there’s a little bit of that in every company. Actually, there’s a lot of that in some companies. Therefore it’s counterproductive for you to ignore it.

We’re going to assume for the moment that much of the chaos in the development cycle is due not to people who are unwilling to make the necessary changes, but rather to the fact that those in the upper ranks of management simply don’t understand that their approach is causing disaster after disaster. This is very often the case. Because business people want to succeed, we have a fighting chance if we approach things in a sensible manner.

Selling the Process

So far, we’ve identified the decision makers, the domain experts, and the people who will actually use the software. The next thing we need to do is insert a pause in the process. Frequently, we’re given fairly high-level requirements and expected to start coding. The fact that the project starts into the design or implementation work at this point is due to no one making the suggestion that there’s a better way. That’s what we’re going to do now.

Development efforts come in all sizes, from one programmer to large groups with multiple teams, and so there’s no one right person to whom you should make this suggestion. If you’re a coder on a team, enlist the support of your fellow programmers and your team lead and go to the project manager. In smaller groups, there may be no officially titled project manager, in which case your group simply talks to the next level up on the food chain. In any event, you’ll have more success if you can first convince your peers and enlist their support in your efforts. If there’s one among you who would make a better spokesman, get him up to speed on what you’re trying to accomplish and then by all means utilize his abilities to further the interests of the team.

After arranging for a little time with the appropriate manager to talk about the requirements, first briefly go over what you have at this point. Because you wouldn’t need to go to this trouble to begin with if you had detailed specs, you should have little difficulty in pointing out the ambiguities in the requirements you’ve been given. You probably don’t need to do anything more than touch on a few high-level requirements and start asking the manager, quite innocently, exactly what they mean. It will quickly become evident that you have insufficient details. You’re not looking for anything more than his acknowledgement at the moment. Once the manager has agreed that yes, things probably should be spelled out a little more clearly, you have an in.

People are always much more prone to lending an ear to someone who both has a problem as well as a proposed solution than to a person who just wants to complain about the problem. Now that the manager has agreed with you that it would be difficult to code from the existing requirements, you simply mention that you have an idea that might help in this regard. If you could get together with a few of the people involved and ask for a little clarification, you could answer your questions and get right to work on the programming. Chances are good that this won’t seem terribly unreasonable, and you’ll be given the opportunity to proceed.

How much of the process you lay out to the manager is going to fall to your instincts and common sense, based on the level of support and cooperation you’re getting. To a manager who is truly supportive of anything that will improve the software development procedures, the process we’re about to walk through will seem logical and productive. On the other hand, if you’re having to fight every inch of the way to make changes, you need to employ what’s known as incremental selling. In this case, rather than overwhelming a less-than-enthusiastic person with all the details of a decent requirements-gathering phase, you instead speak more generally about “just a meeting or two” with the relevant people to clear matters up. That’s easier for them to commit to than some big, fancy, and time-consuming process. It gets your foot in the door, and once you’re there it’s fairly easy to keep having “just one more meeting” until you get the details you need. A little underhanded? Maybe. But, hey, they’ve been doing that sort of thing to us on software requirements for years. For now, let’s proceed with the assumption that you have at least a little support and can put it all on the table.

The Definition Questions

At this point, we’re going to define a set of questions to which we’ll occasionally refer for the purpose of defining a requirement in greater detail. These are the requirement definition questions, or simply the definition questions for short. They are,

• What is the desired action?
• What initiates the action?
• What data does it operate on?
• Where does this data come from?
• What action is performed on the data?
• What supplemental data does it need to perform the action?
• Where does the supplemental data come from?
• What are the visual requirements?
• What are the audio requirements?
• What other systems or subsystems are affected by this operation?
• What are the effects of the other subsystems on this operation?

Most of these are obvious in their intent, but a couple of them require clarification. The questions regarding the visual and audio requirements can easily drift into issues of user interface design. That is not the intent. We still want to focus on what, not how. At times, however, part of the requirement will be visual or audible by nature. For instance, air traffic controllers need to know if data being displayed on the screen is out of date and consequently invalid, regardless of the reason. For example, the figures displayed on the screen for the current runway visibility may indicate a clear day with no visual obstacles. However, if the equipment that gathers this data has malfunctioned, the controller may not be aware of the fact that a fog bank has rolled in and the pilot couldn’t see a Chihuahua if it scampered across the runway right in front of him. Not all controllers have windows. Consequently, it may be fairly stated in the requirements that the controller needs to be given a visual warning indication that the current data is bogus. There may also be a requirement that some sort of audible event take place to get their attention. Both of these accurately state what the software needs to do without getting into how this is accomplished. It’s crucial to keep this in mind at all times. When in doubt, simply ask yourself if the topic being discussed is about what or how. That will keep you on track. Following is an overview of the process we’re going to be using.

1. Identify the decision makers and key participants.
2. Create data entry forms and a database to gather individual requirements.
3. Have a series of meetings to clarify issues on individual requirements.
4. Collect and organize the individual requirements and formalize them in a document.
5. Have the decision makers sign off on the final requirements document.

Seems pretty straightforward, doesn’t it? Actually, it is. Requirements gathering, stripped of all the pomp and ceremony of the big-ticket design methodologies, is nothing more complicated than holding meetings with the appropriate people and asking precise questions about the needs of the system.

Preparations for Effective Information Gathering

Although we have our key players identified and we have a set of concise definition questions, we still need to do a couple of other helpful things in preparation for the requirements meetings. First, set up a database that has, at minimum, a record for a single requirement and fields for the data gathered from the definition questions. If there are a lot of major categories or subsystems, it would be a good idea to include fields for those as well. Whoever is most comfortable with databases in your group can easily go to town from there, but these are the basics. Create data entry forms that will make it easy for nontechnical users to enter this information in plain text and normal language. Make this database, or at least the data entry mechanism, available to all attendees via your company network. Using this data entry form as a guideline, create a document template as well using whatever word processor is prevalent in your company. It’s helpful to have two versions of this, one that the user can type directly into and another that is designed to be printed out and written on. A constant in any enterprise is the fact that the easier you make it for someone to give you what you want, the better your chances of getting it.

Set up a couple of projects in your version control system to house two types of documents. One project will hold the documents that describe a single requirement, and the other will be the repository for the actual formal requirements documents that will be the output of the entire process. Yes, yes, I know, it would make much more sense for everyone to just enter the individual requirements into the database. For a variety of reasons that rarely make sense, this just won’t happen with some folks. Having both the documents and printed forms gives you a fallback strategy for those who can’t or won’t use the database. You need the information more than you need to stand on principles of how they should get it to you. Frankly, if they won’t use the database, the document templates, or the printed forms, but they will answer the definition questions on a cassette tape, take that instead. What we need are results, so take the input any way you can get it.

Now that your infrastructure is in place, if you don’t already have a document that details everything you currently know about your requirements, now’s the time to gather one together. Once you have this, it’s time to arrange the first meeting. As a general practice for all meetings, it’s not only common courtesy but much more productive if you distribute the documents with which you wish your attendees to be familiar a day or two prior to the meeting. In other words, give them enough time to read and digest it before the meeting. A lot of people won’t read it anyway, but it’ll be easier for you to diplomatically ask them to hold questions that were covered in the document if everyone had time to read it beforehand. You’ll find that the other attendees will be supportive of this, by the way, because no one likes going to meetings, and anything to speed them up will make you popular among your attendees.

Another general practice for productive meetings is to always have someone who will be responsible for taking the notes during the meeting and generating a summary document afterwards. Designating such a person makes it easier for everyone else to give their attention to the matters at hand, and also helps to avoid conflicting perceptions of what took place.

At a minimum, in this first meeting you need to have the decisions makers present. If at all possible, you also want to include the domain experts and anyone else who is a power to contend with as far as the requirements go. If you need to work a little harder to arrange a time that everyone can live with, it’s more than worth it if you can get all the major players in one room. Everyone should have had a chance to read over the general requirements of the project as you currently understand them.

Defining the Requirements

The first thing you want to accomplish in the initial meeting is a bit of partitioning. For any nontrivial system, you can usually divide the requirements into some major categories or subsystems. The next step is to build a focus group for each of these subsystems. You may find that some people will need (or want) to be involved in more than one group. Although it defeats the purpose to have all participants work in all groups, this is at times a legitimate need and should be allowed. You may find that there also may be a political need, which is just as important. Identify a leader, preferably by group consensus, for each group. This person will serve as the moderator for the focus group meetings to keep them organized. Of course, you’ll need someone to take the minutes for each group as well. That’s not a terribly gratifying job, so it’s best to get a volunteer if you can.

You now want to give these focus groups a task to accomplish and turn them loose. From the issues in their subsystem, they are to put together two lists: the first is a feature list of all items that they agree by majority vote are desirable, and the second list contains those features that were mentioned but didn’t claim a majority. The focus groups should proceed by first going off individually and making their wish list of features. Detail is encouraged, but it’s not required at this point. They simply need to be able to identify the features in such a manner that everyone in the meeting understands what they mean. After a reasonable amount of time, typically a day or two, the focus groups reconvene and the weeding-out process begins as people lobby, bribe, and argue their way through the wish list. It’s a good idea to remove all the whiteboard erasers from these conference rooms.

As each focus group finishes the two lists, they should distribute them to all members of the complete group. When all focus groups are done, it’s time to reconvene the complete group. At this point, the leader of each focus group walks through the list and lets the group vote on it at large. The same rules apply: majority rules. However, at this point, any decision maker can override the group decision and accept or reject a feature. That’s one of the reasons that the decision makers must be present at these meetings. They’re going to do this anyway, and you don’t want it happening after you’ve already coded the darned thing. After the list of agreed-upon features for each focus group has been covered, the list of features that got only a minority vote is reviewed. If a majority of the overall group decide that it’s a keeper, it moves to the feature list.

If your project is large, you may want to stagger your effort by a series of meetings, one for each subsystem. All-day meetings are tedious and a waste of time by the second hour. If you truly care about keeping everyone’s attention, no meeting should ever go past the one-hour mark.

The output of this meeting or series of meetings is the definitive list of features for the system, albeit loosely defined. The next step is to drop back down to the focus group level. These groups reconvene in their individual meetings armed with their list of features and the definition questions. The output of this process is a record in the database for each requirements, with answers to all the definition questions. How it gets into the database is a matter of what works best for the people you’re dealing with. For some companies, it’s viable to have a workstation in the conference room so someone can enter the data as the questions are answered. In other environments, printing out the forms and filling them in by hand may be the most likely approach to succeed. Even if they do it on a cassette tape and someone transcribes it into the database, it doesn’t matter. Just get the questions answered.

When the focus groups have finished, the information in the database is then used to generate a draft of the full requirements document. Depending on how formally your company likes to do things, this can be as simple as a database report or as tedious as taking the information and creating a separate document in a word processor. The important thing is to do it in a fashion that contains all the details and is in a format that works for the decision makers. It’s a draft of the document you’ll eventually want them to sign. If they’re formal and officious people, you must create a document in the same spirit or it won’t be taken seriously. It may sound dumb, but that’s human nature in the corporate world, and in the end it’s critical that this document—and you and your ideas—be taken seriously.

After the draft requirements document has been distributed, it’s time for another meeting or series of meetings, depending again on the size and the number of subsystems. This time you want some of your top programmers involved as well. There’s an advantage to having all of your programmers in on it if you can manage it, but at a minimum you need the key players for the subsystem that they’ll be working on. If the decision makers want to skip out on the next meeting or two, that’s fine, but the focus group members have to stay because they’re the ones the programmers will question. The same procedure is repeated, and each requirement is visited. This time, in addition to input from anyone in the room who feels the requirement in question isn’t as clear as it should be, the programmers have a chance to review each feature and verify that they have the information they need to design and code from.

Here’s your chance, folks, so don’t be shy. If it’s not clear to you now, it won’t be when you fire up your editor, either. This is one of those rare times in life when it’s okay to put words into other peoples’ mouths. You may hear vague descriptions of functionality that you must help translate into strict and specific statements. An approach that I find helpful is to take the fuzzy statement you heard and repeat it back to them in precise terms, asking for their agreement, such as, “I see. So what you’re saying is that we need to [replace vague ramblings you just heard with a precise description of functionality]. Did I get that right?” Remember, many of the participants aren’t techies, so you may need to lend your skills in that area. Diplomacy is very important when doing this because you want to build allies, not adversaries. Believe me, I learned about diplomacy the hard way.

Although the programmers don’t have veto power regarding which feature stays and which feature goes, they do have the power to flag a requirement as incomplete, meaning that it needs further clarification before it can go into the requirements document. Of course, the more specific they can be about what additional info they need, the better the focus group will be able to comply. Additionally, programmers can flag a requirement as impossible to implement in its current state. For instance, if a feature requires Internet access but the program will be run on some machines that lack that connectivity, it’s a no-go. This does not mean that the feature is dropped from the requirements document, but rather that it is placed on a list for the decision makers to ultimately review. They are the only ones who can make the call to either drop the feature or to ensure that it’s possible to implement (such as, in our example, by including Internet access as a part of the product requirements).

Additionally, the programmers can flag a requirement that turns out to be a design issue rather than an actual requirement. If people have properly answered the definition questions, you shouldn’t see much of this. If it does happen, though, it needs to be noted so the programmers can address it with the appropriate people when it’s time for design.

When the Party’s Over

When all of the requirements have been worked through and there are no more issues to resolve, the draft requirements document is updated once more and distributed. One last meeting is convened with the decision makers and the full group. The goal of this meeting is to get all concerned to figuratively “sign off” on the requirements, but, literally, there should be signature lines for all of the decision makers and the leader of each focus group. The leader of the programmers will also sign. The signatures of the decision makers are mandatory because that’s the point of the entire process – getting the people in power to make a firm and public commitment to a very specific set of features. Getting the focus groups to sign off on the document is simply good politics, indicating that everyone involved has agreed that these are, in fact, the gospel requirements. You never know when this sort of thing is going to come in handy.

Check the document into version control, label it as the final requirements document, and distribute a copy of the signed document to all participants. It’s a good idea to have everyone sign two or more copies at the last meeting if any of the decision makers want to keep an original. You certainly want one with ink on it for yourself. Store it where it’s safe from the gnawing teeth of any stray canines.

Once it’s approved, the requirements phase is officially over. For any future feature requests, there’s a simple response. You can have anything you want, as long as it’s in 2.0. But what if a decision maker requires a new feature? If so, and this may happen, then it must meet the same stringent guidelines outlined by the definition questions, and the subsequent design and estimation phases must be revisited. The bottom line is that the dates must be adjusted accordingly. However, having bought into a process of specific dates tied to specific deliverables, you’ll find that this will be much easier to accomplish.

While the meetings are in progress, encourage the use of email for question-and- answer sessions among members of the requirements team. People have different schedules, and email is the most considerate way to ask questions without interrupting what they’re doing. Of course, email is also the easiest way to get ignored. If you find that some people are prone to doing this, encourage the others to simply camp outside their office door if they have to. Consideration works both ways. Also, remind the team that, as far as the official proceedings go, hall meetings don’t count. If it’s not in writing, it doesn’t exist.

Coping with a Hostile Environment

So far, we’ve been working on the assumption that you’ll get the participation and support that you need from the decision makers to follow this process. Due to politics, resistance to change, or any of the other reasons that people do stupid things in the business world, it may not work out this way. In fact, you may encounter active and extreme resistance to any or all of this. In my opinion, a process is completely useless if it doesn’t fly in the real world, no matter how impressive it looks on paper. If the decisions makers, who are ultimately the only ones who count, won’t allow or follow through with this process, then a couple of things are clear. First, you’re in a pretty bad environment, and frankly you might want to dust off that résumé. Any management that is resistant to a procedure that will help them get the software they want on time and in good working condition is just going to be trouble at every turn. The second thing that’s clear at this point is that, if this is your reality, any help you can get is going to be better than what you have. So, let’s take a look at some shortcuts. It won’t yield perfect results, but any degree of detail and accountability is better than vague feature requests from people who position themselves as untouchables.

No matter what, you must still identify the decision maker. In this particular case, you want a single person, the ultimate authority that can veto everyone else. This shouldn’t be hard. He’ll be the one telling you that he’s not going to support or allow the requirements meetings. This is the guy who you ultimately need to coerce into making a commitment. It’s crucial to know who this person is and to verify that he indeed has the power to sign off on the software system. It’s also still important to round up, or at least to identify, as many of the relevant domain experts as you can.

Forget about the formal document templates for the individual requirements, but keep the database. Just realize that you’ll have to do all of the data entry yourself. It’s tedious, but worth it in the end.

In this abbreviated process, you’re going to follow some of the same steps, and it still starts with your creating a document that summarizes the requirements given you by management. You still need clarification. Because the decision maker doesn’t want to support a legitimate process, you need to target this person with your questions. We’re now on touchy political ground, so be very wary. Use the person on your team who has the best people skills and doesn’t mind storming that machine gun nest. If you don’t have anyone on the team willing to do this, you’re toast. Normal, logical approaches have failed, and you must now decide whether it’s worth taking some risks to try to improve your lot in life. No one can make that decision but you. Your only choices are to update your résumé or get out the sleeping bag.

You want to ask the questions in person. The tactic here is a tricky one, but the idea is to make it clear to the manager that you can’t write the software until you get answers to your questions. If you’re not allowed to have the meetings you need with the parties concerned, you can’t get your questions answered. However, because this is the person who’s requesting the software, he can obviously answer them because he ultimately is the one who must be happy with the system. Your only hope of success is to be pleasant, positive, nonconfrontational, and impeccably logical. If you approach it with a seemingly naïve innocence, it’s harder to get nailed. Gee, you need to write software but you just don’t know what you’re supposed to write, so naturally it’s okay to ask these questions, right?

The implied statement here is that if the manager wants the software but doesn’t want to allow you to go through the common sense steps of defining it, you’re going to be a pain in his behind until you either get your questions answered or he gets irritated and delegates the matter. The danger in irritating a superior is obvious, which is why you want your least-irritating person to perform this mission. The interruptions will be irritant enough. You don’t want one of your guys coming back with the pink-slip equivalent of a Purple Heart. With any luck at all, you’ll at least get some definition out of this guy. You probably won’t have much time each time you corner him, so have your questions prioritized, well thought out, and ready to go. If this is as good as it gets in your world, then, in addition to getting the information, you’ve also been conspicuous enough in your approach that he’ll remember having committed to the details you asked for, if only because he found it annoying.

Another thing that can be helpful in this scenario is to use one of the small pocket cassette recorders rather than trying to take notes. Just be sure it’s obvious to him that you have it, or it looks like you’re trying to pull something over on him. There are also legal implications involved in recording people without their knowledge or permission, and you just don’t want to go there. Simply explain the fact that you appreciate how little time they have so you don’t want to waste it trying to take notes, and then put it in your shirt pocket so it’s not waving in anybody’s face. This makes it a little less threatening. The wise bunny rabbit does not threaten the Bengal tiger. Also be prepared to be told to turn it off. Some people are uncomfortable with being recorded for a number of reasons. If the person expresses such sentiments, comply quickly and with a good attitude. Have a small notepad handy as a backup.

If the person gets irritated enough to delegate, that’s an opening. Pounce on it. If he was previously resistant to the meetings you proposed, probably because he didn’t want to fool with it himself, you can now suggest once more “just a quick meeting or two” with the people he’s trying to delegate to, which is tantamount to agreeing with him. However, you might casually suggest at this point that it might help speed things up a bit and be less of a hassle for the people he delegated to if you bring in “just a couple of other people” who might be able to answer some of the questions. These couple of people are the domain experts you’ve already identified. No need in announcing how many or who unless you’re pressed for it. Even then, there’s no need to admit to the full complement. Mention the person or two least likely to cause resistance. The rest just get invited to the meeting. It’s always easier to ask for forgiveness than to ask for permission.

Be prepared when you hit the meeting, but don’t distribute the documents prior to the meeting as you normally would. Remember, if you’re here, you’re in a hostile situation and need to think a little differently. Any little bit of fair warning you give offers the opportunity for someone to screw it up for you. So, show up to the meeting with copies of the high-level document you prepared and hand it out. What you do at this point depends largely upon the feel of the group. You may find that, even though the decision maker is an inflexible pain in the posterior, the people to whom the work was delegated are actually reasonable and supportive.

You’ll have to play this one by instinct. If you get a good attitude from all concerned, you might try suggesting that you break it into subsystems and letting each of them gather a little information, perhaps getting together with some users or other people that they feel would help with their area. Further, you offer an approach that will help them, that is, the two-list system we’ve already covered, and you slide each of them a list of the definition questions that you were holding on to just in case. In other words, if you end up with a good group, you just slide right into the procedure, quietly and with little fanfare. Don’t push them to do any data entry or any other tedious task. Your main priority is to collect information, and your secondary priority is to establish allies whom you can count on when it comes time to get the requirements document recognized by the decision maker. Your team can handle any of the grunt work needed. You just don’t want this alliance to unravel, so do whatever you can to keep things rolling smoothly.

If you get to the delegated meeting and you don’t have a supportive group, then you simply fall back on the same tactics you used with the decision maker: innocence, logic, charm if you’ve got it, and an overriding goal of getting as many questions answered as you can. Towards the end of each meeting, for as long as you can get away with it, casually ask one or two of the key players if they’d mind getting together with you briefly a little later in the week to “just answer a couple of questions.” Target people that you need the information from the most. If you can pull it off, you can use this approach to hold a series of mini-meetings with a couple of people at a time. In a similar fashion, you can drop by a person’s office (email is useless in this context) and ask if they could spare a minute or two for a couple of questions. In other words, your mission is to gather information, even if it breaks down to house-to-house fighting. All of this is a real nuisance, but still not nearly as much of a pain as trying to cope with deadlines and pressures when you’ve only been given the vaguest of requirements that you know will continue to change on you.

What if you simply don’t have physical access to the decision maker? This is a hard situation. At that point, shoot for people directly under them in the food chain and work the same tactics. The bottom line is that, if you don’t get some cooperation or access at a reasonably high level relative to the people who make the decisions on your software, you’re pretty much done for. However, I’ve worked for large, international corporations, and, although the general directive to go forth and create software may come from the CEO, in reality the people who will approve your software as being finished are typically not too far from you in the general scheme of things.

In a similar fashion, regardless of which of the preceding tactics you’re forced to employ, your ultimate goal is still to get an official approval of your detailed requirements from the decision maker. It’s best to get one in writing. However, if you’re in a hostile or unsupportive environment, that just ain’t gonna happen. In such a case, you take the finalized requirements document—the best that you could put together under the circumstances—and make it available on the network after having labeled it in version control to prevent someone from tinkering with it later. You then send an email that this document exists and how to find it to anyone with any clout in the decision-making process, in other words to all perceived decision makers, as well as all domain experts. In your email you state, diplomatically of course, that to the best of your understanding here are the only things you’re aware of that you need to implement in the software and that, unless you hear otherwise, it’s all you’re going to implement. The language should be nonconfrontational and more along the lines of telling them that you’d be grateful for any clarification or input that they might have. If you get any takers, try and walk them through the definition questions on any features that they may want to sneak in. After a round of that, update the document and repeat the email. When you send an email and you don’t get any response back for a day or two, then that’s as good as it’s going to get. However, when the release crunch comes and people start trying to wedge in new requirements or wiggle on existing ones, you’ve got a paper trail (print out and save at home all of the email responses you get) to help fight off the last minute changes. It’s not as good as a signature from the decision maker, but it’s a little more ammunition than you would have otherwise had.

Politics Are Never Far Away

Even though we’ve run the gamut here from a constructive and cooperative environment to one that is hostile and unreasonable, some of the basic concepts remain unaltered. To define a given requirement, you need to ask specific questions. To tie requirements to a date, you need to formalize the final requirements and have the decision maker acknowledge them. As important as all of the issues we’ve covered here may be, perhaps the most critical consideration is realizing that, if you get anything less than full support when trying to nail down your requirements, you’re dealing with political issues. This is a double-edged sword. Although politics are unsavory to most of us and certainly dangerous if ignored or handled poorly, programmers can also employ them to get what we want. This is most prevalent in the requirements-gathering phase, as you have people with their own personal agendas jockeying for what they want. That’s politics, pure and simple. However, you’re going to find that, although we talk about practical, nuts-and- bolts programming issues regarding condensed design approaches, low-level estimating techniques, and so on, political considerations will never be far behind. If you make your living in the business world, it’s an inescapable reality. In the end, the programmer who successfully delivers his software is most often the person who has good technical skills, good organizational skills, good political skills, and is willing to use each when called upon.