The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Tense to use in specification documents

What is the correct tense to use when writing a functional specification, for instance?

I find that the natural tendency is to use future tense, as in "the user interface will consist of two buttons...", because the user interface does not exist yet when writing the spec.

I am worried however that the spec will seem outdated when the progtram has actually been written but the spec is still being kept up to date.

I am new to spec writing as you can probably tell... :)
Riaan van den Dool Send private email
Wednesday, October 26, 2005
 
 
Present tense.

Read:
"The user interface consists of ..."
as
"The user interface I'm describing in this spec consists of..."

The interface alreay exists, just not in code.
  -tim
a2800276 Send private email
Wednesday, October 26, 2005
 
 
A requirements document will use something like the future imperfect.

The user should be able to .....
The programme will...

Whereas, as Tim says, the specification which is the answer to the Requirements document will be in the present tense, except when talking about sequences of actions and where you have to talk about previous steps in a process.
Simon Lucy Send private email
Wednesday, October 26, 2005
 
 
Some good references for spec writing:
Guide to Specification Writing For U.S. Government Engineers: <http://www.ntsc.navy.mil/Resources/Library/Acqguide/spec.htm>

SpecRight: <http://www.abm.rda.hq.navy.mil/aosfiles/tools/specright/>

Simon's correct, requirements use the future imperfect, though phrases like "should be able to" and "will" are right out ;)
Former COBOL Programmer
Wednesday, October 26, 2005
 
 
I think the future tense is more common. But its really not that important, as long as you are consistent.
Andy Brice Send private email
Wednesday, October 26, 2005
 
 
That you even have a spec is a vote of confidence from me.  ;)


Go for future tense.
KC Send private email
Wednesday, October 26, 2005
 
 
I remember some weird tenses from Latin.

Future Subjunctive Imperfect (?) Or Something that runs along the lines of:

"The interface will should have been..."

No one's realyy going to read it, so you might as well bill out a few months and make it incredibly difficult to read.

:)

Wednesday, October 26, 2005
 
 
Use 'shall' if you want to feel important ;)
Anil
Wednesday, October 26, 2005
 
 
> I am worried however that the spec will seem outdated when the progtram has actually been written but the spec is still being kept up to date.

LOL.  But - a way to approach this problem is to make the functional spex and the user documentation the SAME document (or at least the one evolve into the other).

And that argues for the use of the present tense I think.
Abstract Typist Send private email
Thursday, October 27, 2005
 
 
In the U.S. aerospace and defense industry at least, you use "shall" because all the "shalls" are listed in a verification matrix you step through at customer acceptance testing to demonstrate each one is implemented and works according to the specification. I think the reasoning is that you can use "is" in its various forms without the confusion whether or not you're listing another specification (like "...this will allow future functionality to be added on"). i.e. if it's a "shall" it's part of the specification and has to be implemented, if not then it's not.
Bill
Thursday, October 27, 2005
 
 
If you use present tense the spec should be able to rolled into a fat appendix for the system Help with less tears.

Come to think of it, write the Help first and use it as the spec. Should dissuade invoking the future past pluperfect.
trollop
Friday, October 28, 2005
 
 
I have come to " a2800276" conclusion. After you build something and you read the spec it just sounds strange, so I try to write everything in present tense.
son of parnas
Friday, October 28, 2005
 
 
I agree with present tense.  It makes the document more compact and I think it's easier to read.
Karl Perry Send private email
Saturday, October 29, 2005
 
 
" I remember some weird tenses from Latin."

Well, you can always program in Latin if you wish: http://www.csse.monash.edu.au/~damian/papers/HTML/Perligata.html
Berislav Lopac Send private email
Sunday, October 30, 2005
 
 
Present tense.. such as "the button opens a dialog which shows the following items" ...
 
but there is a issue that nobody has addressed; functional specs are not write once, read many times items.
 
One of my functional specs is now over 30 or so revisions - the (complex) functionality has been developed over several stages over 3 or more years.

That leads to a problem. In stage 1 of the development I say the "The bar-graph button when activated displays a bargraph"  - no, I _don't_ write specs like this ;-) 
A year later I add the new improved pie-chart function.
"The pie-graph button when activated displays a piegraph"

I now have two lines in my spec - one of actually indicates functionality which is present (past tense) and one which will exist once the spec is implemented. The changes are marked with change bars & coloured font, but it always worries me.

In the end I stick to present tense, but think I would prefer to use future tense & edit the document to past tense. Oh, and in some cases it is hard to avoid refering to items in the past or future - eg "In the previous version we did X but now are to do Y" and "in the future we will support.." but I try not to as a spec should reflect reality to some extent.
Grant
Monday, November 07, 2005
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz