Fog Creek Software
Discussion Board

Specifications? How?

[This post is a re-post of a question posted at my own site]

Before I start of writing this post, I’d like to refer to certain other sources to prove that Specifications are important for any software development. It works the same as house construction: no company is going to build a house without a blueprint (heck, they won’t even get permission to build it otherwise!).

First off, lets link to the Joel test, specifically the part about writing specs []. Any questions about why you would write specifications read this article []. More information can be found here on Wikipedia [].

The question I have is: how would you go about to document the specifications? This PDF [] talks about possible options on pages 109 and 115, but how would you do this?

Everything always boils down to what you really want to do with it. Well, actually, not very much. Specification is firstly a means to communicate the exact soon-to-be implementation to those who should sign-off the project. Secondly, it should be the basis for a technical design document and later the actual implementation. Furthermore, it should provide the definitive answer for testing: should this box be red or blue? As a last needed feature is to be able to quickly see the differences between specific versions of the specification (“What was changed since version x.y.z?”).

So what would be a good way to document these specifications? Because I want ways to quickly show differences between versions I thought about CVS and docbook (together with a tool, Norman Walsh’s diffmk, to generate a proper HTML document containing differences between two versions of the docbook’s XML document). But this proves a little bit tiresome, especially when large volumes of pictures and diagrams are involved. A possitive side of the usage of CVS is that multiple people can work on the specifications. Thats why, in my opinion, dismisses solutions like Word and/or Excel.

It is good to know that other people are struggling with the same problems [].

Basically the core of this post is to ask: “What ways of specification would you use in similar circumstances?” Got any answers to this? Do you want to discuss about this topic with me? Write me an email [], post a comment on this thread or post a comment at this page on my website:

Jilles Oldenbeuving
Saturday, July 10, 2004

Before deciding on how to write specs you need to settle on a development approach. Waterfall, Iterative, Extreme Programming, etc.

Then you can pick a documentation tool appropriate for the job. There are many companies that sell specialized tools for each approach. 

Anony Coward
Saturday, July 10, 2004

You definitely need some way to include text and diagrams in the Specification document.

This leads me to PDF documents, Word documents, or RTF documents.

You also need some way to point out the differences between two versions of the document.

Typically, my company uses Word documents to put all this stuff together.  And yes, they can get quite large.  We use Visio for diagramming, or UML Studio for UML diagrams.

We use an Excel spreadsheet to store a 'check-list' version of the specification items (aka Requirements).

We've also used an Access-based database to store and track version meta-data for deliveries.

Saturday, July 10, 2004

I struggled with this same question for many years while I tried many different approaches.

For what it's worth, about a year and a half ago, we settled on using a combination of the following to document our applications, which are "rich client" Windows applications.

1.  Domain Model
2.  Glossary
3.  Use Cases
4.  User Interface Model

I believe this approach could also be used to develop Web-based applications, or probably just about any other software application that involves interaction with an end-user.

The core of this approach is outlined in one book, on which our approach for parts 1-3 are based:

Use Case Modeling (Bittner/Spence)

This approach has given us a very straightforward way to both document requirements as well as track our progress and plan our work.  There are many books written about use cases, including a popular one by Alistair Cockburn, but I think the approach outlined by Bittner and Spence is simpler and easier to manage, even though they share many of the same ideas.

Feel free to e-mail me if you would like more specifics. It's one of many possible solutions, but in 10 years of developing commercial "shrink-wrap" software applications, this approach has worked the best.


Saturday, July 10, 2004

I really can't stand Word docs anymore! Anything but Word. I think they should be in html.

Saturday, July 10, 2004

Word docs for "describing" and "lists", Visio for "diagram" and "UML" (or UML'ish), all stored on a sharepoint WSS with the "maintain version history" option enabled.  Server is backed up regularly with the source archive in SourceValut.  Works great and has a version history of sorts.

Saturday, July 10, 2004

The basic problem with the current software that I've tried is that you use one program do do your design visually and another to create a comprehensive to-do list of specs.  And changes in one are not automatically reflected in the other.

This seems analagous to the problem of UML editors (in the past, anyway): you'd design in the UML editor but then need to update your code to reflect the charts and diagrams.

Syncing the diagrams and the code was a problem.  (Now that I think of it, this is a general problem in lots of areas: keeping different representations of a problem sync'd. I guess that's the (currently unrealized) promise of XML.)

My ideal documentation software:

One program that would let you:

1.  Include semi-interactive screen shots.
Ability to have hyper links, so if you click on a button on the screen shot it'll show you another screen.
Ability to annotate the screen shot.

2. Gather all of the annotations from the screen shots into some sort of outline.

Thus, you DESIGN in GUI mode (which is how most uses think, IMHO), but you create nice, neat text documents that are easier to work with as a "to do" list.

Basically something like DEMIN but which gathers all of the annotations, etc. into an outline. Then the outline can be modified as well.

Any opinions on this?

Mr. Analogy
Sunday, July 11, 2004

Mr. Anology:

Look up literate programming.

But given that people can't even keep comments in sync with code 5 lines away, I don't think it's really the answer either.

(P.S. XML has nothing to do with this.)

Sunday, July 11, 2004


As with all these type of questions "it depends"

Remember the purpose of the (Customer Requirements) Specification is to transfer what is in the Customer's head into the Designer’s head. The best way of doing this is dependent upon many factors.

Do the Customer and Designer understand a common notation, such as UML?

What type of product are you trying to specify?

How good is the relationship between the Customer and Designer.

Does it need to be formally documented for the Pointy Haired Suits? Or would the minutes from a meeting/ in the pub be good enough?

What format would the Designer prefer?

Would the Designer like you to indicate the changes between document up-issues? Or will he need to do this himself anyway. If so, what's the point in you doing it?

What type of design lifecycle will use be using?

Don't take this the wrong way. This forum will be able to give you ideas for documenting / expressing requirements (eg WIKI, web pages, Excel, Doors, Whiteboard photos etc) but the most successful method will be if you can meet with the guy and girls who will be using the specification and asking them what the best format would be.

It's a bit radical for some projects, but why not get them to write the specification? Invite them to your meetings etc while you decide what you need and let them write the spec and then let you review it before design?

Ian H.
Sunday, July 11, 2004

*  Recent Topics

*  Fog Creek Home