Fog Creek Software
Discussion Board

Writing Specs - Not my job

How do you get around the fact that a lot of programmers and/or companies feel that it is not the job of the programmers to write specs.

One place I work at feels it's the sales department's job to write specs.

Sunday, November 3, 2002

Just to add, that as a consequence of the management feeling that the Sales department should write specs they never get done.

Sunday, November 3, 2002


What spec you are talking about?  Are you talking about a functional spec that details the interface, program features, and the like?  Or are you talking about the low-level technical specification that spells out all of the minutiae for implementing the functional spec?

I would argue that in most cases it is NOT in the best interest of anyone to let a programmer write functional specs.  Based on a lot of programmer-spec'd software that I have seen, my position is that left alone, programmers typically write software with arcane, unfriendly interfaces that users cannot use.

Leave the high level functional specification and interface design to those who know how users think.  Have the programmers write the tech specs, and let them tell the managers how long it will take to write the software to the tech spec.

Karl Perry
Monday, November 4, 2002

You might not have to write the spec but you should certainly be able to refuse unspecified or poorly specified work. Educate your customers in what you need from them, hold their hands because they almost certainly don't know what you need from them.

Tony E
Monday, November 4, 2002


Great one, Tony!  Us QA and QC folks would LOVE to refuse unspecified or poorly specified systems to evaluate.

The problem is, of course, that probably over half (just a guess) the systems getting built today would never get tested if the QA staffs dug their heels in and refuse to test the "mystery-meat" they get handed.

But I'm all for it, really. As long as the QA/QC folks don't end up getting lynched for it, then cool!


Monday, November 4, 2002

Anon, any place where the sales department is writing the specs - any specs - is not a very high quality place. You should look around for a better job.

Karl might think his sales guys are good at writing specs, but that says he's not developing anything very complex, and that he doesn't hire very good programmers.

It's funny how this theme keeps cropping up lately.

Software is complex. Designing it at the business level and at the user level requires an understanding of that complexity. The people with that understanding are programmers. The best programmers run rings around non-programmers at BA, UI and other design.

Salesman's design: "we just need some boxes here and there and we have to support 30 different file types. I said we could do it by next week. Hey look, effort, focus, we're a team here, guys."

No wonder there's no much junk around. And junky websites too. Such is life.

Must be a manager
Monday, November 4, 2002

"Software is complex. Designing it at the business level and at the user level requires an understanding of that complexity. The people with that understanding are programmers."

Software is indeed complex, internally. Designing software that works well at the business and user level does require appreciation of that complexity.

User and business level activities are complex. Designing software functionality, behaviour and presentation requires understanding of that complexity. The people with that understanding are important. Some might be programmers right now, some might be in sales, even others might be in marketting, quality assurance, support, testing, whatever.

Monday, November 4, 2002

Programmer's design: "Hey look, we've got this algorithm with all these parameters here. Just in case I might need to change one later I will create this nice options dialog and put them all in. These users must be fools that they fail to appreciate the level of control I gave them."

In case this is not obvious, this is just as bad a practice as the salesman's design, and both should be prevented. Neither prove that one or the other discipline is more approriate.

Find the right tool, or in this case person, for the job. Determine which skills are required and focus on those. If you happen to have a programmer who happens to have more of those skills than your salesperson, choose the programmer. But evaluate the skills and the people at hand. Silly generalisations or fabricated scenario's won't help you one bit.

Monday, November 4, 2002

Actually, my problem here is that the developers ARE writing the specs. Business comes up with some fuzzy idea about what they might want and thereafter it's all techies, who don't necessarily understand the business processes, writing documents. Then coding, then integrating.

And that's about the point business comes back from their big-lunch-at-the-pub and says "no... that's not what we meant!"

Specifying takes domain knowledge as well as technical knowledge.

Katie Lucas
Monday, November 4, 2002

"Specifying takes domain knowledge as well as technical knowledge."

And in addition, communication skills that allow you to specify in such a way that both the domain expert AND the technical expert understand and subscribe what you have specified.

Each of these disciplines is difficult enough in itself. It would be very inconsiderate to think that one discipline can easily carry the burden of one of the others. In general, that is. Specific circumstances might occasionally lead to compromises. But that would be based on the problem at hand and the skills of the people at hand, not the nature of each discipline.

Monday, November 4, 2002

I have no problem with the sales people writing the requirements.  Heck, anybody can write them as far as I'm concerned.

It's up to the development team to write the specs that fullfill the requirements, and possibly get the specs signed off by the requirements writer.

Gerald Brandt
Monday, November 4, 2002

One of the underlying tenets of Extreme Programming is facilitating maximum communication between different groups of people.  For example, at the beginning of the XP development cycle, the customer and the designers sit down and collaborate on the requirements.  No group simply hands a completed document to another group.

I think this is a case for collaboration.  The business people should talk to the programmers about their specs (assuming that there are no full-time designers).

Brent P. Newhall
Monday, November 4, 2002

I agree with Gerald and Brent. In the end it doesn't really matter who wrote the specs as long as all the interested parties sign off on the spec.
In our group here, the software group writes the specs after talking to the sales department/scientists and who ever might have valid requirements for our system. After that, all those parties review the specs and decide/argue on the importance and priority. Once everyone agrees, they sign off the specs.

Another approach that Microsoft uses that Joel has mentionned a few times is to have Program Managers write the specs.
I think that approach is probably best; however, it might not always work for smaller companies where a position like that might not be justifiable but I could be wrong here.

Does anyone know any other companies beside Microsoft that use that concept?

Wednesday, November 6, 2002

*  Recent Topics

*  Fog Creek Home