Specification philosophies

>
> Agreed. In particular, when I myself read specs that (under my 
> impression) repeat information that was already provided before/by 
> reference, I start asking myself: "why are they repeating this? -- is 
> this intended to *change* something that was said before?". So, if 
> something's just intended to repeat something that was already 
> specified somewhere else, it makes a lot of sense to say that, instead 
> of leaving readers like myself confused :-)
>

This is confirming evidence for what I thought -- Julian, you have an 
extraordinarily good memory, even among this techie crowd!  I do not 
find repeated information to be confusing because with my poorer 
short-term memory I have forgotten the details of what was already 
said.  I also tend to read quickly and sometimes skip over details.  
Other readers fall along this range but I'm guessing Julian would be at 
nearly one extreme of fine memory/detail and me (I've always supposed) 
somewhere in the middle.

Repetition need not be in the same form.  I've noticed four different 
ways that functionality *should* be repeatedly described in a spec and 
there may be more:
  1) Explain the model.
  2) List the requirements, including those that follow from the model
  3) Show one or more examples that meet the requirements and illustrate 
the model
  4) Formal definition, schema (ABNF or DTD or other) of syntax

When exactly the same thing needs to be repeated (e.g. method FOO has 
the same error conditions as method BAR) we can consider cut-and-paste 
of small sections, or using a table or some other way to make the 
information obvious.  It's the silent or assumed references that scare 
me most.

Lisa

Received on Thursday, 2 December 2004 01:36:33 UTC