Fog Creek Software
Discussion Board

Convincing my boss about functional specs

How can I convince my boss to get out of a prototyping mindset ?

I have tried telling him that doing a functional spec is important in ironing out the user experience, but he just won't get it.

The problem is that he focuses too much on the technology... and I have tried to explain that the "how to do it" is really the easier part of the design than the "what to do" (the user experience).

Has anyone been in a situation like this ? What could be done ? How could I point him to resources like this site and other books, without rubbing him the wrong way ?

Wednesday, April 10, 2002

Hi Neuman,

Like most bosses, your boss will probably only be convinced by 'bottom line' arguments.  So, can you point out (with evidence) any disadvantages of his current prototyping approach?  Can you contrast this with concrete advantages of your approach?

Alan Cooper's book 'The Inmates Are Running The Asylum' makes a pretty good attempt at arguing why a comprehensive system design is a good idea before a single line of code is written.  He makes his arguments in an entertaining style, and he is writing for a business audience - so this might be the way to go.  He specifically deals with issues such as the perils of a prototyping culture.

All the best,

Wednesday, April 10, 2002

If you're right (and of course you are), you'll run into numerous situations in your daily work where the consequences of not writing specs show up. The most obvious problem is time wasted building the wrong thing. The next time it happens, why not take some "design notes" of the changes and ask him to review them before you implement them, telling him you just want to make sure you're getting it right this time. If your boss values predictability, shipping on time and spending less money per feature, he'll agree.

Wednesday, April 10, 2002

I may be wrong, but are prototying and funcitonal specs mutually exclusive?  In fact, could one can say prototyping is just one facet of a funcitonal spec?  Or one can say protptying helps nail down the functional spec... Whether its worth doing, that really depends on the nature of the app, and the complexity, etc

Wednesday, April 10, 2002

Well, I'm a QA guy, so folks failing to define requirements directly causes me pain. Usually a lot. More so because I'm really a "QA" guy, and not a QC guy who just uses the term "QA" loosely. Problems in the process like this reduce quality and make more work overall for everyone. One 6 month gig I had was to come into a new shop and set up a SDLC process for them, so I'm into the development process itself, in all its various styles. I'm not religious about it, either. I'm neither for nor against old-style waterfall or XP. Each is a tool. Use the right tool for the job. Use the wrong tool for the job and you have problems.

It's been my somewhat cynical experience that senior management - whether they are senior level developers or more "pure" management folks - who don't just already "get it" are not going to "get it". I've about concluded that there's nothing one can do to convince them. If the guy with the authority is a senior devloper and he's still not bothering to define requirements -- and make sure I know what they are when he dreams them up -- then he's gotten where he is primarily by being a cowboy and it's very unlikely he's going to change.

If the guy with authority is a more "pure" management type, he's often got a sales background, and I haven't seen any better luck in convincing these folks why cutting corners is a false economy either. I could fill a book with the stories I've heard from sales folks, senior developers, project managers, and the like as to why we don't have time to get our requirements reasonably defined. Or why I need to be in on the process from the early stages.

One problem I've seen is emotionally charged words such as "process". It's become all too commonplace to criticize "process", so as soon as I tell people we need to work on our process, they shut down because all they actually hear is "process" and they think about old-style single-pass waterfall with requiremets analysis going on for months before anything else is done, etc. It doesn't matter that I was talking about *iterative* process, or "lighter" approaches, and that I've said by that point that we do not necessarily need to prepare heavy, persistent paper artifacts for every single thing we do. It doesn't matter that I've said the key is not the artifact itself, it's making sure that everyone who needs info has it when they need it -- whether it comes from standing around a whiteboard for half an hour together and then following up with an email capturing the requirements you just defined.

As soon as I said "process" they shut down. This has not been the problem in every case, just one of the many I've seen. Won't go through the rest here - you've probably seen them all yourself anyway.

With the vast quantity of books and articles out there that all say you need to have some friggin' idea where the hell you're trying to go and that you have to figure out how to tell when you've arrived, I can't see how anybody would not "get it". But, it turns out such folks are all too common.

The only thing I've seen that's had any effect is the same thing that works with little kids when mom and dad tell them not to touch the stove - it's hot. The kid doesn't listen until they burn their fingers. Eventually, some of these people are around and watching when something blows up and then they start to get it. Some of them.

Pretty cynical, I guess. But I've just watched it happen too many times and expended too much personal capital with such folks too often to not feel pretty jaded.

Oh, and interestingly (well, maybe not, but here it is anyway), whether you're in a consulting environment (i.e. where your hours are directly billable and you have to fill out timesheets and justify your time, etc.) or whether you're in a product environement (i.e. you're not "on a clock" and effort is not explicitly tracked), you'll hear the same argument for not working on specs (requirements), but from opposite sides.

If you're having to track your hours, then unenlightened management will not want to make any improvements, or expend effort to collect any metrics, because they can't justify the hours -- gotta be billable all the time. OK. I get it. I understand: billable=revenue=paychecks. I have an engineering degree. I understand that math. But this is a classic case of a greedy algorithm producing a globally sub-optimal solution. It's the old saying about being "penny-wise and pound-foolish."

OTOH, If you don't have to track your hours, then nobody wants to start doing so, so you have no metrics for the amount of effort getting wasted by screwed up practices -- the actual cost isn't visible.

Different path, same final result.

It's hard to get ROI that the more "pure" business types want because you can't get a denominator for the fraction. e.g. you can't do what it takes to tell what doing things badly now is costing, so you can't come up with a basis for comparison with an alternative solution that might be better.

How to convince your management? Hell, when you find out, let me know! I'm in a good shop now, most of the people either get it or are getting it, so I just consider myself lucky.

F.J. Weiland
Wednesday, April 10, 2002

I just (this morning) tried to convince the project manager on our new project that we need a functional spec, but to no avail.

We've got a requirements document that describes the functionality of our software using incredible sweeping generalities. There are no pictures (or descriptions) of dialog boxes. The document is replete with things like "administrators will be able to perform license partition management functions" and other similar vague requirements.

I primarily write the technical documentation (and do just a little programming here and there on small projects), so it drives me out of my mind to work from these requirements documents. Especially since I need to write user documentation at the same time as the developers are writing code.

I have to interrupt developers 5 or 10 times a day to ask them questions about the interface or functionality (because the answers aren't in the requirements document). They are obviously annoyed that I keep interrupting them, but I have no choice. They are the only source of knowledge. Plus, after I've written documentation on a given feature or tool, the company management will often meet to review the progress, and they'll tell the developers to re-do some feature implementation because its not the best way. So the developers re-write the code and I re-write the documentation.

Anyhow, I met with the project manager this morning to express my concerns and make some suggestions. The response: "I would love to use detailed specs, but we just don't have time".


I tried.

Benji Smith
Wednesday, April 10, 2002

> [...] There are no pictures (or descriptions) of dialog boxes. [...] The response: "I would love to use detailed specs, but we just don't have time".

If you end up implementing anything at all, then eventually you will have those detailed specs: ie the specs will be whatever you have coded. So, like it or not, you're going to have specs sooner or later. So why not make it sooner. If the boss isn't interested in that level of detail, that needn't matter ... if even only you and the developers are interested in having specs, then IMO you can get together early rather than late, to decide on the specs before you all start coding.

Christopher Wells
Wednesday, April 10, 2002

The trouble is that the developers don't seem to want specs. And I can understand why. Developing is more fun when you can make design decisions instead of just implementing a system that has already been fully designed.

Plus, the developers have the same mentality as the product manager. They each spend 12 hours a day working on the code. They bring code home with them and work until the wee hours. They continual have a look of fear and exhaustion on their faces. And they seem to believe that writing a spec will push back the date that they can start coding, but not the ship date. So to them having a spec means an even more furious development pace.

No one here seems to remember all the backpedaling and re-implementations that we went through on our last product (and the weeks of wasted developer time caused by that backpedaling).

Benji Smith
Wednesday, April 10, 2002

Chris wrote: <If you end up implementing anything at all, then eventually you will have those detailed specs: ie the specs will be whatever you have coded. So, like it or not, you're going to have specs sooner or later. >

Chris - we're thinking alike, man! I made this point in private conversations and also in a few "public" meetings at work -- that there is no such thing as an "undefined requirement." All requirements are fully defined--when you stop coding.

The key issues are:

1) are the requirements visible to those who need to know them or not when they need to know them, and
2) are the requirements correct?

Of course, if they're not visible, then it's damned difficult to figure out if they're correct or not. Hmm... pretty easy way out for some folks... "Let's not define the requirements, then whatever we build will be right!"

I tried to make this same point - that they *always* get done, so we might as well make sure the right people know what they are and that they are what they need to be.

The folks who "got it" were the ones who "got it" already anyway; the others just didn't.  dammit.

Oh - and a note: I'm using the term "requirements" broadly to include "any statement of an observable and measureable behavior or attribute of the system or its components", so that includes what folks call "requirements" as well as what they call "specifications". Which, BTW, I maintain are exactly the same thing - there is no intrinsic difference between specs and requirements; it just depends on where you're "standing" at the time. But, that's a different thread.

F.J. Weiland
Wednesday, April 10, 2002

Benji, maybe double-check with them your assumption re. why they don't like specs: your statements "developing is more fun" and "look of fear and exhaustion" seem mutually incompatible!

Re. "Developing is more fun when you can make design decisions" I'm not suggesting they miss out ... it's *more* fun IMO to do the job well, and for *them* to do the design (and specs) with someone else who's interested (e.g. you).

I used to genuinely wish that my boss would assign a tech writer earlier to a project, rather than after the end.........

In any case, if you're able to walk around (instead of they, who are apparently nailed to their consoles) then IMO you're in a position to make a really valuable contribution to the project, acting even as an assistant product manager or project manager though you needn't claim that title ... maybe what you need to emphasize is that you can help them (in doing their work), even more than you emphasize that you need their help to do yours.

I've found that work gets done by "circles" of semi-like-minded inter-cooperating people... so my suggestion that if you can't get sense from your boss, if he or she is really uninterested in all that, perhaps you can make sense with someone else (with individual developers or team leaders).

Christopher Wells
Wednesday, April 10, 2002

I'll try again with the project manager. He's actually a really bright guy with a lot of knowledge of our domain and an understanding of the technical issues we face as well. It caught me a little off guard when he balked at my suggestion of a complete spec.

He (like all of the management here) is just experiencing growing pains because we're trying to do the work of a 40-man company while only having 25 actual people on staff.

Hopefully, if I volunteer to help write the spec, we can actually get it done. Of course, I'm no less busy than anyone else, but I realize that a spec is the most important thing, and should therefore be done first.

I honestly don't think he'll take me up on my offer, but I hope to at least have an impact on the thought process that's so prevalent here. We need to shift resources from the _urgent_ tasks to the _important_ tasks.

Benji Smith
Wednesday, April 10, 2002

> "a complete spec" ... "is the most important thing, and should therefore be done first."

That can be an unpopular viewpoint!

IMO, it can work well in some industries (e.g. telecomms, where you're implementing to some already-well-known protocol), and not in others (where being nimble, feedback-driven, and just-in-time is an important part of your salvation). It is a difference between for example "waterfall", and "spiral" (or 'iterative') software lifecycle.

In contrast I'm imaging that you capture the 'specs' as they are created... that you participate in meetings (one or more people, plus you) where you make drawings of the GUI elements, and then break up, they to start coding and you to start documenting; or that they get into the habit of giving you each new sketch as soon as possible after they have dreamed it up while working late alone some weekend night.

It shouldn't be, IMO, that they must all idle until after your specs are complete and formatted and sent for typesetting and bound and printed and signed off on (I'm exagerating), but equally it's beneficial if you, the specs, the documentation in general, and even the end-user manual (which may be the only ultimate specs) are also not left to lag behind the coding. You're an essential part of the team (assuming that end-user documentation is essential to the product). My opinion is that if they treat you as part of the team, they (developers and management) may very well find that you're not only essential but very useful too, that what you do adds information, adds value, even to their development process.

Christopher Wells
Wednesday, April 10, 2002

> no intrinsic difference between specs and requirements; it just depends on where you're "standing" at the time. But, that's a different thread

I use the terms as follows:

-Requirements - what the customer wants
-Specifications - proposed system architecture
-Design - details

A waterfall will generate these in the above sequence. Each phase has its own form of QC (or do I mean QA?):

-Design - Unit testing
-Specifications - Integration testing
-Requirements - Acceptance testing

Christopher Wells
Thursday, April 11, 2002

The trouble with the iterative design process that we've had in the past is that things tend to get done over and over again, like so:

1) Developers and management have a meeting to discuss "requirements".

2) Developers start working on the code. They design the interfaces and the user interactions.

3) After several weeks (or months, depending on the stage in the development lifecycle), the developers release a new alpha build for testing.

4) Developers and management meet again. Generally, management likes what the developers have produced, but could they just change the way XYZ feature was implemented? The dialog boxes are all wrong or the user workflow is confusing or something. Their change requests are always valid and important elements to the design of the software.

5) The developers revise all of the work they've done over the last few weeks (or months) to try to do things according to the new preferred user workflow.

6) Developers meet with management again. There is a new feature request from management. Implementing the feature will change the data structure of the product that has been implemented so far. But it is a very important feature.

7) The developers re-engineer the system to accommodate the new feature. The new data structure is not the ideal way to accomplish things, but it's a reasonable compromise between the old data structure and the ideal new structure. If the original requirements had included this new feature, things would be done significantly differently.

Throughout this process, I've written documentation three times. The developers have written code three times. Everyone is pulling out their hair because deadlines approach and we miss them and the developers work like dogs to get things done and then their work is tossed out to make room for new features (which are good and important features, but which should have been in an original design).

Of course, I'm not saying the developers should sit around playing checkers while we write 900 page full-color spec. The developers are an important component in the design process. Their contributions to the spec are valuable. But, I'm telling you that we've already got an "iterative spiral software life cycle" for designing our software. In other words, nobody knows quite what they want until they see it. And it's maddening.

The saving grace is that it's really neat software and we have hoards of huge corporations (in a very specialized industry) just drooling to shell out $60,000 for a site license. And nobody else makes software remotely like ours. I think that will be the saving grace that prevents this project from meeting its natural darwinian end.

Benji Smith
Thursday, April 11, 2002

sherlock_yoda wrote {
Like most bosses, your boss will probably only be convinced by 'bottom line' arguments. So, can you point out (with evidence) any disadvantages of his current prototyping approach? Can you contrast this with concrete advantages of your approach?

For the past 1 year I have been working in a "
new product initiatve" team at a large company that has been toying with some product ideas (who hasn't :-))

The problem is that there is no long term focus or commitment to any particular idea. It typically starts with a new idea catching the fancy of my boss, then a prototype is built without functional specs or proper requirements, which obviously lacks in a lot of respects. This results in a lack of enthusiasm and commitment for it, and then it gets dropped.

Maybe someone experienced in product development could have some thoughts on this... maybe Joel, Michael ?

How are products developed ?

According to <a href="">Jim McCarthy</a> of Microsoft, the product vision is the key.  I have'nt read his book "Dynamics of Software Development", is it any good ?

Thursday, April 11, 2002

So if in step 2 they'd do design before coding; and if you could capture their design on paper and let management try to sign off on it (or to suggest ammendements) then steps 4 and 5 might be merged at least somewhat into step 3. Step 6 is harder to deal with: standard work-around are to try to suck the suggestion out of them earlier, design for flexibility (or design for minimality) to make ([un]anticipated) changes more easily, or to push the new feature into a next release so as not to delay this release.

Christopher Wells
Thursday, April 11, 2002


I really like your documentation of the 7 steps of development used at your company. Why not title it "Official Development Process of <XYZ> Corportation", print up a few copies, and put one on your wall. If anyone asks, offer them a copy of it while smiling wryly and say "I thought it would be helpful to document our process."

X. J. Scott
Thursday, April 11, 2002


It looks like we're going to try to implement an informal version of what you're describing (combining our "iterative steps" before the coding takes place).

According to my project manager, he and the developers have now met to hammer out some of the specifics left out of the requirements document. They are in the process of designing all of the dialog boxes for the product. They'll put screen captures of all these interface components into a file with a brief description of each.

So within a week or so, we'll still have our vague requirements document, but we'll also have a set of images describing the product interface. It's not quite where I would like it yet, but it's a significant improvement. (Apparently management has recognized the inefficiencies in our development process, and they're starting to do something about it).

The real key will be what is actually done with the design at this point. If we stick to the design, great. If changes are made to the design, and the design documents (requirements & interface specs) are updated, that's great too. But, it's still possible at this point that the new interface specs will be an exercise in futility and that we'll go through the same 'iterative' design process I described above.

In fact, just one second ago (as I was typing this), one of the lead developers approached me with the VB project files and asked me to produce the document with all of the interface components.

I hope this is our first step towards having real workable specs in the future. Even through we're not quite there yet, it looks like everybody is moving toward that attitude.


Benji Smith
Thursday, April 11, 2002

Benji, I don't think that a spec will solve your problems.

To summarize your current 'process':
1.  Developers and managers develop requirements
2.  Developes design and code
3.  Developers release alpha version
4.  Management comes up with changes that NEED to be done
5.  Development scrambles to do changes
6.  Management comes up with more changes that NEED to be done
7.  Development scrambles to do changes

Do you really think that in your case having a piece of paper at step #2 will keep #4 and #6 from happening?  Or will they, being management, just say, "I don't give a damn what we agreed to on paper, we need to do X!"?

Tim Lesher
Thursday, April 11, 2002

Writing the spec consists of more than just jotting down what was talked about during a "requirements" phase. The most important part of specwriting is the thought process that goes into designing the system to meet the requirements. The paper itself is only a "log" that helps everyone remember those thoughts.

Writing a spec will not prevent changes. If no thought goes into writing the spec, it will not help a bit. A carefully thought-out spec prevents all those changes that could be foreseen at the time it was written, but it doesn't prevent the world from changing.

It all comes down to thinking before you code. Sadly, way too many programmers prefer playing with their source code until it works over at least trying to think things through.

Thursday, April 11, 2002

Tim said:

Do you really think that in your case having a piece of paper at step #2 will keep #4 and #6 from happening? Or will they, being management, just say, "I don't give a damn what we agreed to on paper, we need to do X!"?

B said:

Writing a spec will not prevent changes. If no thought goes into writing the spec, it will not help a bit. A carefully thought-out spec prevents all those changes that could be foreseen at the time it was written, but it doesn't prevent the world from changing.


As I'm working on assembling the list of dialog boxes (with pictures of each), I'm starting to see improvements already. Apparently (I didn't know this was happening until this morning), the developers took the requirements document and went off to design the interface. Two days later, they had all of the dialog boxes for the program designed.

They took those designs back to management and said "Like this?". Management said "No, you need to make these changes..." Two days later they came back with changes and said "So, like this?" and management said yes.

In our old process, the developers would have taken six or eight weeks to make the dialogs fully functional before making a presentation to management. We've reduced the amount of wasted time from six weeks to two days. I'm happy with the process so far.

It remains to be seen whether all of the important features and changes have been targeted yet for this product. I hope not, but I know the possibility is there. At least, at this point, we've taken the user interface design and made it more efficient. Now we need to do the same with functional design.

I'm not enamoured with the idea of a written spec, per se. I just stronly believe in what the spec _represents_: that somebody has put some serious though into the design. It is expected that the process of defining the spec will lead you to find features you had forgotten about and weed out inefficient ways of doing things.

Benji Smith
Thursday, April 11, 2002

I agree with you guys that design specs or the thought process behind building a software as per the requirements is the most neglected or ignored aspect of Software Development.

If that process itself would be streamlined and well understood, the process of creating software would be a straight road and no exploration over the mountains.

Even I am a CSQA certified QA professinal, and have faced the problem where the management believed that 80% of code could be reused to develop a new system for a banking project. The basic fact that code reuse is possible, but each system being different in its requirement specs, needs to be designed and developed using reusable components only, and not by reusing entire systems made earlier could not be understood by the management. This led to highly inaccurate estimation, and the team is still struggling to meet deadlines, working and reworking over the 80% reusable code and exploring the additional 20% code.

Am also looking for ways to convince management about the necessity to have a process in place for requirement analysisi, documenting requirements, system design (high level and low level). If you come across articles and info on this topic, kindly share.

Chetan J Shah
Saturday, October 4, 2003

*  Recent Topics

*  Fog Creek Home