Re: Documentation requirements: Re: lynx-dev LYNXCFG:, LYNXCOMPILEOPTS:

[David Combs]

On Fri, Nov 19, 1999 at 02:50:24PM -0500, T.E.Dickey wrote:
> > 
> > From: Philip Webb <address@hidden> 
> > 991119 Klaus Weide wrote:  
> > >>PW> a good point, provided it is documented somewhere, 
> > >>PW> but it isn't: not in Users Guide or Supported URLs. 
> > >KW> let the inventor of LYNXCFG: do it... :) 
> > PW>yes, if we all accept that authors of features & their modifications 
> > PW>should be required to document them (allowing for language 
> > difficulties), 
> > PW>but i hesitate to ask TD to take on the task of doing the requiring. 
> >  
> > Tom, I won't hesitate to at least _ask_ your opinion - what do you 
> > think about the idea that before a new or changed feature is accepted 
> > requiring the contributor also provide documentation? 
> 
> given that it would be a radical change in policy, I don't think it would 
> work out.
> 

But who else CAN write it?  Or at least write, however badly,
however un-stylishly, explanations of:

.  Why this feature was needed.

.  What one can do with this feature (a little brain-storming,
   please), with examples of exactly HOW to use it.

.  The various options, and WHY they were added, and what you
   can do WITH them.

Who else can do this other than the person who thought it
was so important that he/she spent the time and effort to
create it.

---

Also nice would be, within the code, comments explaining
why he/she chose this particular way to implement it,
and what other ways he/she COULD have done it, and WHY
he/she chose THIS way.

Again, who ELSE but the implementor can lay out these things?

---

Later on, if need be, someone ELSE can flesh it out, and
rewrite it to better English style -- IF that turns out to
be needed.

---

Once the software is turned over to lynx, well, it's too
late for documentation -- no one has time.

Only by REQUIRING it for acceptance will it get done --
and that very time is when it is all freshest in the
implementor's mind.

And that time is also when it is EASIEST to do it.

---

You asked for opinions; you're getting them!

David