Re: Lines of documentation per LOC

[mat@mole-end.matawan.nj.us]

In article <EACHUS.94Oct25190056@spectre.mitre.org>, eachus@spectre.mitre.org (Robert I. Eachus) writes:
> In article <1994Oct25.170005.27711@sei.cmu.edu> lpb@sei.cmu.edu (Loic Briand) writes:
> 
>  > Is there any document or source of information that provides
>  > an accepted (?) ratio (lines of documentation / lines of code) for a 
>  > software design document (SDD)?
>  > Talking with people around me, I got values between 10 and 0.1, 
>  > but no rationale other than: "the description has to be complete and
>  > sufficient to allow modifications" and stuff like that.
> 
>    At first I couldn't believe that this was posted by someone at the
> SEI.  Then I noticed it was posted by an industrial affiliate, who may
> learn something while he is there.  And on second reading, I realized
> he had gotten the right answers and dismissed them!  Maybe he won't
> learn after all.

If the original poster will look carefully at the `stuff like that,' I
belief he will find all the criteria he needs to determine whether
the design documents will meet their needs.  He has, in other words, a
specification for design documents.

His job is now to determine what design documents will meet that spec.

He's looking for another spec, one that doesn't require him to think,
one that doesn't require him to expend engineering effort on every step
of the engineering process.

It don't work that way.

If you get a set of criteria that tell you how to judge your work against
the real needs it must meet, treasure them.  Paint them on your walls,
and repeat them in chant as you enter and leave the office.  Begin every
design document with page on which those criteria are written.

Cherish and apply the wisdom you receive.

Or read Schwartzkopf's book, and particularly the section where he has
nailed down the five main responsibilities of mid-level army leadership
_and_ management.
-- 
 (This man's opinions are his own.)
 From mole-end				Mark Terribile
 mat@mole-end.matawan.nj.us, Somewhere in Matawan, NJ
	(Training and consulting in C, C++, UNIX, etc.)