Tom Chi  

Wanted - Spec Owner

December 9th, 2005 by Tom Chi :: see related comic

Everyone thinks the detailed spec is a great idea, and it really is. There’s just two problems — no one wants to write them, and no one wants to read them.

Theoretically, a specification is a complete description of all thinking and discussion around a product or feature. It is supposed to be the archtypical “living document.” In reality, it is updated in fits and starts, and new thinking is not always captured or read when it is captured. Lastly, there is the document ownership issue. Since specs need to capture all dimensions of a product, accessibility, marketing, internationalization, etc all must be represented and these contributions only complicate the writing/reading process to an absurd degree.

Given the trouble with specs, perhaps it’s time to start thinking of ways to accomplish what specs accomplish in more organic ways. Extreme programming with its “war rooms”, IDEO with its “hot teams”, and agile with its “daily standups” are all means of opening channels for communication that were previously decided in spec reviews and recorded in specs. But what is really working?

Which process is working best for your team? Have you mastered the spec process, and if so, how?

22 Responses to “Wanted - Spec Owner”
Robby Slaughter wrote:

Hi. I’m the guy who always challenges the premise on OK-Cancel. I’m not just a contrarian, I *promise*. Here goes.

“Everyone thinks the detailed spec is a great idea, and it really is.”

No way. I know *tons* of managers and programmers who can’t stand specs. “Why do we need a spec, I know what I want it to do?” Or, my favorite “The finished code will be the spec.”

My tactic generally is to refuse to do *anything* that takes more than 20 minutes unless it’s written down in a way that satisfies me. That doesn’t mean you have to have a spec—you can do lots of things in 20 minute spurts—but it forces the discussion to realize that software is ENGINEERING and requires the same level of discipline used in other forms of engineering.

Josh wrote:

Well, as someone who’s stuck owning the specs, I whole-heartedly agree. Everyone wants them. Nobody reads them. I waste too much time writing them. Previously, my solution was to replace the spec with a detailed web prototype, which not only showed how things looked, but how they acted as well. This worked great for web apps, because although it didn’t replace the spec, it allowed the spec to be a lot lighter, since the nitty-gritty details could be derived from the prototype. Now that I’m working on Java Apps, it’s not quite as feasible, because too much time would be spent trying to make web technologies behave like Java to convey the functionality, so it’s back to long detailed specs. If someone has a better answer, I’m all ears!

Jason Yip wrote:

This is more triggered by this sentence from the comic:

“Well how can I write it if I don’t know that the application is going to look like?”

If knowing what the application looks like is required to write the spec, then I think that spec is unnecessarily too detailed and will either suffer from fragility or the project will suffer from premature rigidity.

Overall, I prefer the approach described here:

Chris McEvoy wrote:

I try lots of face to face discussions and a mind-map on my laptop to capture the details.

J. Scott wrote:

Back when my parents were engineers there were these people that companies hired that were called technical writers. Their job was to write the specs and to keep them at all times in sync with changes made to the design.

Apparently, sometimes back then it was even possible to deliver projects with all features intact and on budget.

Chris Law wrote:

I find that for web applications that a mockup with some annotation works best for small teams. It’s lightweight enough that you can get it done quickly and you can update it easily enough so it doesn’t get out of date.

Some of the higher level stuff around goals and objectives can be captured in a single one pager that doesn’t change and as long as your team meets on a regular basis (and is small enough) I find this works well.

Jon wrote:

Great comic; reminds me of the Good Old Times at Trilogy … :)

Bryce Johnson wrote:

Well the one thing that is for sure is that no one ever likes to write specs (in any form) and starting them is often the hardest part. I’ve found that UX and IA people are often asking to get involved earlier in the process and the easiest way to do that is to take responsibility for the specs. Project Managers will often magically find extra budget if it means that they don’t have write all the specs. Obviously this depends on your organizational setup but I’ve seen this happen many times. I’ve always felt that designers should own the specs because they have the skills that will help present them as a unified team vision of project success. I’ve also found that the best way to get developers to help with the specs is to provide with them with something they can tear apart at first and then get them to make estimates.

Dave wrote:

This is one of those great, “it depends” debates. First of all I think it is a bit extreme to say that no one reads specs in all environments. In my world, Quality Control lives on the specification. The specification is the place where agreements are captured between design and engineering. Often the implementation is WRONG, so I can’t really agree with the idea that the coded application is the living specification.

Also, in compliance audited offerings like for pharma, finance, etc. you have to have a specification for legal reasons, or to keep your customers happy. (Oh! our customers read our spec sometimes.)

Now, I can say that having a specification these days is really a bear because everyone wants to be nimble. I don’t mind writing a spec. I mind constantly updating them.

One solution would include requirements software that breaks down requirements into units that are a lot more manageable. If I just had to edit a line and a small graphic each time and didn’t have to open an entire 400-page specification and edit the table of contents every time I made a change, it would be a lot easier on me. These requirements tools usually offer issue/resolution tracking pieces so that the discussion around a requirement/sepcification can be in the context of it. Moving from bugzilla to word to CVS or whatever gets quite annoying.

In the end, some organizations using agile methods may find ways to reduce a paper trail, but these will not be large corps that worry about the #1 reason for specifications. People die, get sick, or otherwise leave and if you don’t have it documented somewhere your knowledge goes out the door.

Tom Smith wrote:

As a developer you probably know what you are going to build. As a client you have a good idea of what you want. The two things will be inevitably be different, no matter how careful both parties are.

The specs are most frequently read when one party has massively diverged from it… or a legal case is imminent… They are often not the “plan” but the “safety net”.

Jon wrote:

I’ll be the first and probably only person to freely admit that I enjoy writing specs. It feels like “making wrong things right”, and I get a ton of satisfaction out of structuring things like that.

Eya wrote:

Hi all, great topic.
I’w working in a very big italian company in charge of designing sites for mobiles ..almost 1 millon users accessing’em everyday.

to build 50+ products we’ve set up huge teams of developers and managers, plus designers (of course) and found that specs are the only way to manage communication.

We can’t spend hours repeating what specs are, so documents are necessary.
Around what could be the perfect way to express them, well… hard point: at the end of the day a very detalied storyboard including graphics is 100% clear to anyone but hard to maintain.. while written docs are read by no one, as you say, and subjects to misunderstandings of all sorts…

Will let you know in ..50 years.. :)

Eya wrote:

Ah, forgot one point.
there’s a huge debate aroun who should be “the Owner” of those docs.
is he or she the manager responsible for the “product” in toto?
Is he the designer who gets in the storm if the “product” is found ugly/unusable ..maybe following managers’ suggestions?

Both are open points: specs and ownerships..will get back in 100 years guys

Bob Salmon wrote:

No specs, eh? How do you know when you’ve finished? How do you know you’re doing the right thing? How do the testers know what’s supposed to happen? (There are people, other than end users, testing it?) How do you say RTFM when there’s no M? (No, I’m not confusing user documentation with specs - if a tester says “when I do blah, should the system go bibble?” you can reply RTFM if and only if there’s a spec. Otherwise it’s UTSL.*)

Ah, I think I’ll make this car more lightweight by removing the steering wheel and the brakes. Sorted.

I’m sure agile works in some circumstances, but I work in the UK and have colleagues in America and India - we can’t sit next to each other very easily.

Sorry - sleep deprivation makes for lack of fluffiness.

* Use the source, Luke.

Daimon wrote:

Come on guys just because writing specs can be tedious it doesn’t mean they are bad. If you are working on large critical transaction apps you need specs. If you are working on some “one off” member database with a web front end and some business rules you need specs. As a senior IA myself- I write the specs and maintain them. Maybe I’m just a nerd or a glutton for punishment but I enjoy it. IAs need to work closer with development teams. I found in my experience that the better the relationship is with development the better the end product. Don’t cop out and say, “I’m not technical.” Learn- get a book, take a developer to lunch and find out how you pull data out of a database and the rules you need around it. This has always worked best for me. Just my 2… Daimon

Ronie wrote:

Specs is the most precious thing a project could have. However, “plain-text” specs and “diagrams” specs are not the best solution for all environments. Some sort of story-board is really useful, little prototypes, even made in PowerPoint, could be equaly useful.

I think we are payed as software engineers to know which ones are useful in which environments. Any extremist position is kind dangerous, I believe.

From my experience, teams up to 6 or a very partipative client can make “plain-text specs” very lightly. However, I still keep them for at least the key parts of the systems.

Mircea wrote:

Specs ARE useful. But they are not maintained. Lack of time, extra costs not wanted to be factored in by anyone, etc.
What I want to do in our company is implement a wiki which has the easiest way to be updated. You can structure wiki documents on fragments, sections, links are maintained, etc. Nobody is the “owner” but rather a group of authorised users can update the spec page as time goes by. Easy to edit, easy to add content. (fingers crossed in hoping that it will work…)

susie wrote:

Oh no and have the “Inmates running the asylum”!!!

Jon Steiner wrote:

We’re trying to find an appropriate way to write specs for our next generation product.

As one of the people involved, here’s been my take so far:

- all the non-spec methods - xp, agile are intended for small groups. In larger groups, it doesn’t work as well

- its not that people don’t want specs (usually people in the process are *happy* to be given a direction, hence the comic), but don’t want to be bothered with maintenance. Making maintenance easy should be a high priority.

- alot of the newer requirements management software packages treat the spec as a fluid entity (not a ‘document’ per se). There are other issues under the surface, of course, but if the team is flexible, and everyone respects that everyone else’s time is a limited resource, then this kind of approach can work. See Requisite Pro, DOORS, etc.

We will see what we will see. But so far, this is my perception of a better way to do requirements in my present organization.

Felix Plesoianu wrote:

In my experience, the problem with specs is that
customers don’t actually know what they want. They
change requirements when you least expect them
(even daily) and they like it that way.

Otherwise, I think, writing and maintaining the
specs shouldn’t be that hard. After all, there is
no need to spend pages specifying a login form…

Barb Hernandez wrote:

Seems like when there are with problems maintaining specs there is a larger problem in that there is a lack of understanding about what is being designed. I opt for more “upfront” design to develop an understanding of what to describe in the spec - then write it.

Specs should be appropriate to the project - heavier for larger, more detailed projects, lighter for small features. That being said, it all depends on what’s being designed, seemingly-small features may not be so small.

I always include a mockup and how it interacts with the rest of the system. For large systems I use a series of smaller docs - by feature or UI area. The trick is not forgetting the “big picture” and how the little pieces work together.

Overall, specs are good in my opinion. Writing specs in an “Agile” dev environment is a challenge. Things often move to fast for the spec to get written and often when things don’t work as we all thought they would. Then it’s back to the drawing board for the developer or “sorry it’s too late” for the user. Either option is not optimal and the formal is certainly not agile.

t.davis wrote:

First company I worked for was RUP all the way — detailed specs. R&D consisted of some 70 people; each “new feature” project team was organized / run by a business analyst who selected the team members he needed from each functional area: documentation, training, engineering, QA, and so on. The devs could code from the spec and match the UI mock-ups; the writers could prepare draft user and training manuals; the QA group could write test plans. The specs changed as needed and everything trickled down. The process was efficient and reliable.

Next company, next job — R&D consisted of some 8 developers, a report designer who doubled as a technical writer, and a product manager (Prd Mgt reports to the CTO). No heavy specs here. R&D adopted Agile practices and produced a “release” for an existing product every quarter.

The PM managed the incoming feature requests, produced requirements documents that listed the feature requirements according to a release/milestone schedule, and prepared detailed, annotated wireframes (i.e., UI mock-ups) that doubled for a specification. He also participated directly in development as the owner of the UI, which sometimes required getting his hands dirty in code.

This approach certainly worked *for this group*. The engineers mostly wanted to know what each screen looks like, what the workflow should be, and what were the behaviors on each screen.

The lightweight approach to the specifications simply meant that the coding could begin earlier; customers could “see” the product working earlier and give feedback; the app could evolve during the development cycle according to their feedback; and in the end it would be closer to what the customer really wanted.

Leave a Reply

OK/Cancel is a comic strip collaboration co-written and co-illustrated by Kevin Cheng and Tom Chi. Our subject matter focuses on interfaces, good and bad and the people behind the industry of building interfaces - usability specialists, interaction designers, human-computer interaction (HCI) experts, industrial designers, etc. (Who Links Here) ?