Fog Creek Software
Discussion Board

Organizing Software Specs and Specs for Websites

I’ve read Joel’s articles on writing software specifications. But I couldn’t find any specifics on the layout of these documents. He makes mention of a 500-page spec he wrote for Excel. How is such a massive document organized for easy readability? I imagine a document that large becomes difficult for the creator to maintain and for readers to navigate.

Also, I’m very interested to hear how people write specs for a non-trivial website or web-based application. For example, it seems like the spec for FogBugz would be very similar to a spec for a typical database-driven website.

Saturday, December 20, 2003

Two key things to remember when writing specs:
1) If I were a coder, would this spec tell me what to do without having to ask anyone?
2) If I were QA, would I be able to answer "does the app meet this spec" with just "yes" or "no"? (would I even know what to test?)


Saturday, December 20, 2003

I am pretty sure the Excel specification Joel was referring to was actually a technical specification (also known as a design specification). 

"... For example, it seems like the spec for FogBugz would be very similar to a spec for a typical database-driven website."

The type of spec you create really depends on who your intended audience is.  For example, a requirements document is typically the only specification a project sponsor or an end-user might read.

I am sure someone after me will post the URL for the Techwhirl forum (technical writers forum). You might find several discussions there that are relevant to what you trying to accomplish.

One Programmer's Opinion
Saturday, December 20, 2003

I also would be interested in some examples or info on how people  construct specification documents.

All of the ones I have seen in the three companies I have worked for are pretty weak, not specific enough and full of silly manager speak.

I am developing my own software in my spare time and I created two documents, a functional spec and a technical design.

The functional spec seperated the system into 4 modules, listed what the user would be able to do in each, what the limitations would be, sensible functionality not supported etc..  It also contained three detailed case studies of imaginary small businesses and how/why they were using the software.

The technical spec listed database structure, 'sub-systems'  and notes on the technology bieng used.

As the documentation got bigger it became much harder to know where to put information.

Saturday, December 20, 2003

One of the things I like about Eiffel and its associated development environment is that it allows you to put a lot of specification information directly into the code using its contracting mechanisms.  This is typically what I do, where possible.  For items that cannot be captured in this fashion, I generally put into special comments in code headers.  There's also some graphical design tools to help specify non-logical constraints (structural constraints, temporal constraints, etc).

Having the spec in this form makes it easier for me to keep everything in synch and makes the information easy to find for developers.

Saturday, December 20, 2003

In my experience, Word's outline mode actually isn't half bad for managing largish spec documents. The key is to take a few minutes to decide what should be a Heading 1, a Heading 2, and so on, and then apply these rules consistently throughout the document. Then you can turn on the document map pane or switch into outline mode and collapse/expand the relevant sections of the spec. Adding bookmarks can help so you can quickly jump to key portions of the spec.

One thing I don't like about using Word is that its native file format is some proprietary binary thing, but recent versions of Word also let you save in a lossless XML format, which plays nicely with your source control system and diff tools.

For smaller specs, I usually just use text or a lightweight text-markup format like POD (plain old documentation).

John C.
Sunday, December 21, 2003

Could be worth reading -

Ben R
Sunday, December 21, 2003

I've set up templates for project plans and requirements based on IEEE standards some time ago. They prove to be a good foundation.

- IEEE 1058 Project management plans
- IEEE 1233 Requirements specification
- IEEE 828 Configuration management plans
- IEEE 1016 Software design descriptions

The official documents you have to purchase, but with a bit of googling ready made templates will surface.

Monday, December 22, 2003

In Joel's article on functional specs he defines a functional spec thus:

"A functional specification describes how a product will work entirely from the user's perspective. It doesn't care how the thing is implemented. It talks about features. It specifies screens, menus, dialogs, and so on."


I would question whether that is true, and in fact, I would suggest that this definition (or whatever similar definition one might carry in one's head) is one of the problems with functional specs.

A functional spec should define the functions of a program, not the implementation of those functions. Specifically, it should not define how the function is implemented in terms of the screens, menus, dialog structure and so forth. That is a matter of design, which is the process of translating a functional spec into a plan for implementation.

For example, to use Joel's what time is it, web site. The functional spec of this might be something like this:

1. The web site will show what the current time is.
2. The web site will provide a facility to store the time zone of the current user of the web site.
3. When a time zone is stored, the time will be shown corrected for that time zone.
4. The web site will obtain its time information from the NIST atomic clock.

This sets out the functions of the software, not the how of the software. It does not, for example, set out the web pages used, what they will look like, what the navigation will be and so forth.

Perhaps the best way to set out the functions in a functional spec is to give a series of use case scenarios (without all the fluffy stuff from UML), simply a set of scenarios that covers the functionality that the user will need. Again, not specifying dialog flow, screens, menus etc, but rather goals and achievements:

Scenario 1: Joe wants to know what time it is, so he pulls up the software and reads the time.

Scenario 2: Fred lives in New York, and wants to see the time in his correct time zone. He tells the software what time zone he lives in, and subsequently, all times shown to Fred will be in that time zone.


This can be augmented by other types of requirement that cannot easily be expressed in this way (performance, deployment and so forth.)

By designing the detailed implementation of the software (that is the user interface) in the functional spec you are confusing what you want to achieve with one particular way of doing it, and consequently, you cannot separate what is important from what is optional.

Needless to say, in the majority of software products being developed today (whether shrink wrap or web sites) the design of the user interface is usually the most time consuming and challenging part. So the need to separate it from the actual functional requirements is all the more important.

The additional advantage is that scenarios and lists of requirements are relatively small compared to a full technical specification, meaning that this multi function document (tester, customer sign off, sales/marketing design as well as coding spec) is much easier to assimilate.

Jessica Boxer
Monday, December 22, 2003

*  Recent Topics

*  Fog Creek Home