Hixie's Natural Log

2007-01-29 21:06 UTC Writing specifications: Knowing when to stop

When you're writing a specification, it's important to define the terms you use. For example, if you use a term like "browsing context", or "application window", or "pointing device", you should make sure you have a definition of that term. It's important, because you are really inventing a new word for yourself, for your specification, to help you write the requirements concisely. It's a bit like defining macros, constants, or functions in a programming language.

However, you do not need to define words that are plain English words (or whatever language you are writing in). For example, you don't need to define the word "is". You don't need to define the term "purely advisory". However, you might well be asked to define terms that to you seem quite clear. The way to tell if you need to define the term after all is to look at the dictionary definition. If the dictionary definition seems to you to be pretty close to what you were saying, then you don't need to define the word — you're using it appropriately. If the dictionary definition doesn't cover what you mean, e.g. because you're using it in a metaphoric way (e.g. "window", "desktop"), then you'll need to define it.

Don't fall into the temptation of discussing the meaning of the word "meaning".