On a $55M project, I had thousands of pages of specs that were totally
useless. As soon as a spec was six months old, the product changed so much
from the spec, that the spec became a dusty book on a wall size bookcase.
Ken actually helped out on this project but he may not remember the
documentation aspects in 1987.
The only thing that really worked for ongoing maintenance of that project
was a startup that I loaned space to in return for initial releases of their
design product that would reengineer a couple of million lines of COBOL code
into a reasonable design document which clarified dependencies. The
maintenance programmers said that was the only documentation in the shop
that really helped them because it was up to date with the latest release of
We do get pretty good marketing specifications now that document key use
cases and screen shots along with logic before development starts to build
(along the lines of Jacobsen's analysis approach). These are not
requirements documents which are viewed as a marketing wish list. Marketing
must roll up their sleeves and really defined the workflow. They are short
documents that allow product marketing to clearly communicate with the
developers. Sometimes they are only two pages for non-GUI functionality.
Sometimes a couple of dozen. We use the XP approach and cut minimal code so
if it is not in the spec it doesn't make it into the backlog. If it is not
in the backlog nobody works on it. This creates a dynamic tension that
reduces development tasks while product marketing strives to get the spec
lean, clean, clear, and complete in order to get what they want in the
CTO PatientKeeper, Inc.