Fog Creek Software
Discussion Board

Referencing Software Specs

Often times, a task is made challenging by simple adminitrative burdens.

Based on my experience with just a half dozen specs, that a major challeng is the admin burden of :

1. Referencing specs (or clients failing to do so).

2. Being able to manipulate thos so that we can see the items organized by IMPORTANCE or by COMMONALITY. (I.e., changing the screen color and applying a background graphic might have a lot in common and perhaps ought to be done at the same time, but might have vastly diferent importance.)

I've used MS Word to do this, but the outlining SUCKS.  Outline view is difficult to read because the word wrap sucks. It doesn't wrap nicely at the beginning of the text like:

14.  Milestone 5
      This will sdf ;lkajsdf as;lfkjds faslfj
        asdjfas flkasjdf aslfkjasd fas

Intead it wraps like:

14.            Milestone 5
this will asdfj fsd;lfsdjf sfsdfjas djf
asdf;laskdfj asdflasdfja sdf

I know this seems picky, but its an ADMINISTRATIVE burden. Makes the whole thing harder to read.

(BTW, if you think that simple ASCII layout is just as good as Rich Text Format, then you're missing why HTML took off.  It allowed anyone to create a nice, easy to read formatted document and ANYONE could read it).

Mr. Analogy
Thursday, July 22, 2004

Wow, you actually want the specifier (I'll call him a 'user' for now) to decide what features are more important than others?  Our users merely tell us everything is critically important, nothing can be left out, and walk away with their problem solved.

And if you DO actually find a user who is willing to go through this exercise, usually they are 'trumped' by another user of equal or greater authority, who has a different order of importance.

This is one of the nice things about the XP process, that since features are only implemented a small clump at a time, the user MUST decide which feature they want implemented first.  Note this gets around the 'importance' problem.

Thursday, July 22, 2004

Using a bug tracking system for feature requests works fairly well for me - the issues (relationships between items, dependencies, priority being different from severity) are similar.  Seems too formal, but I don't go straight there, I start with keeping a to-do list for projects I'm working on.  If I have an idea about a project I'm not working on, or the list of ideas gets too long, or if (despite the fact I /think/ I'm working on the project) it's been on my desk long enough to get dusty, I post it into the bug system.  Doesn't solve the problem of generating the spec, but it does organize the data.

For someone whose bug system is differently designed/used from Joel's recommendations, it wouldn't work at all.  For an initial spec of a nonexistent project it doesn't work either - there I've taken a decent spec template (I think it was at but it's been a while) and cut it down to the parts I thought were most useful.  The template looks really excessive, but our cut-down version ends up running about 4 pages.

Thursday, July 22, 2004

I'm on a project where we're using this idea:

- have a spec in a word document.  (We did not write the ones we have, they were supplied to us).
- set up an Excel spreadsheet.  There's one row for each requirment.  You can have whatever columns you like, so your can sort and filter etc to categorise and "slice and dice" the requirements.  In one column, you have hyperlinks to the word document.  The hyperlinks point to bookmarks in the word doc.  So that you can just click on it in Excel and it takes you straight to the right part of the word doc.

The hyperlink formula looks like this:


(See Excel help on "Create a Hyperlink" for details).


John Rusk
Thursday, July 22, 2004

*  Recent Topics

*  Fog Creek Home