Re: Lines of documentation per LOC

[lpb@sei.cmu.edu (Loic Briand)]

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.
|> 
|>    The right amount of documentation is a function of the code!  I

Robert, I am not totally stupid. I _know_ that the amount of documentation is
function of the code.  The problem is that when you have a client who ask for
10 lines of doc par LOC and you have budgeted 0.1 (based on the expected
complexity of your code), you have to prove your point.
All you can do is look for data, books, articles, and other material
possibly writen by people who know what they are talking about.

Lets clarify for you what I am looking for: data-based statistical ranges like:

Embedded Real time program, Ada
 . Complex algorithm:           10 to 20 lines of doc / LOC
 . Intermediate complexity:    0.6 to 9 
 . Simple sequential program:  0.1 to 0.5
Accounting program, Cobol
 . Complex algorithm:           10 to 25 lines of doc / LOC
 . Intermediate complexity:      4 to 9 
 . Simple sequential program:    1 to 3

Then if you estimate that 10% of your code is complex, 55% intermediate, and
the rest simple, you can predict a documentation effort, based on _data_.

|> have written pages of doumentation for a dozen line package.  I have
|> also written code with very sparse documentation--in some cases just a
|> mathematical sequence and its source.  Anyone looking for magic
|> numbers in this area is doomed to be frustrated.  

It is not about magic numbers, it is about _measuring_.
Documenting a design is not an activity fundamentally different of designing
or coding. A lot of attention is given to the predictability of the design or
coding time. The same attention should be given to the documentation time. 

I suppose you know that it is impossible to predict any duration without
reference data. So, tell me: how do you budget/plan the documentation of a
program? (Note: I am not talking about a package written in my kitchen, but
of something larger, say, 1 million LOC). Do you use data recorded on
previous developments of similar complexity? So there are existing data? 
So may be somebody published something? Guess what: it is what I am looking
for. 

If people like Capers Jones published data saying things like "the detailed
design productivity in function points per staff month ranges from 25 to 300
(median: 150)", I don't see any reason why there would not be relevant
data published on the design documentation.

And BTW, I am learning a lot at SEI. Great place for a resident affiliate.

|>                                                   Anyone working
|> for him is probably going to be damned to a Procrustean bed.
|> --
|> 
|> 					Robert I. Eachus
|> 
|> with Standard_Disclaimer;
|> use  Standard_Disclaimer;
|> function Message (Text: in Clever_Ideas) return Better_Ideas is...
.


---------------------------------------------------------------------------
--  O p i n i o n s   e x p r e s s e d   h e r e   a r e   m y   o w n  -- 
--  Loic Briand  SEI Resident Affiliate  lpb@sei.cmu.edu  (412) 268-6674 --
--  Sponsored by Wilcox Electric/Thomson-CSF           briand@wilcox.com --