Kerberos documentation relay

[Ken Raeburn]

(I only noticed Sam's reply today...)

On Aug 11, 2010, at 15:39, Sam Hartman wrote:
> Hi.
> 
> First, I agree that API documentation should have been solved yesterday
> and starting as soon as possible is an incredibly good idea.

Yes.

> I continue to believe that function level documentation should belong in
> the header file or code, not in some website or database.  If you want
> to generate a website or database that's great.  However, Perl, Python,
> Java, Kerberos for Mac,Linux's ALSA, and many other projects demonstrate
> that in-code documentation works reasonably well.

I'm inclined to agree.

But, more than this, I think if a reasonably good mechanism is chosen, so that progress can be made, it ought to be just a matter of a few hours of perl/emacs/whatever hacking if it's later decided that the wrong direction was chosen initially.  Getting into a position where the text can be updated is more important than making sure the project isn't started with anything less than the absolute ideal tools.  (Perfect vs good...)

A couple of starts were made towards using doxygen in the header files in the past, which failed for reasons other than the choice of doxygen, I think.  Is there any reason to reverse direction now?

> I don't believe any of the past efforts have failed because the
> documentation was in-code--they have failed from an attempt to handle
> things all at once.

Being able to do the work in pieces and/or in stages seems like a big advantage to me -- *almost* a necessity.

> With the proposed committee, etc, I assume you are trying to provide a
> mechanism for external contributors to get docs in.  In particular, I
> assume you are not trying to raise the bar for existing people with
> commit access to document their work.  If so, that seems like a great
> idea.

I kind of think it may be overkill.  There are already processes in place for accepting code changes (patches in the bug database; commit access) or wiki updates.  If the documentation goes into the source tree or the wiki, the existing processes could be used, and the "committee" would be whoever deals with the relevant sorts of changes now.

And Zhanna's proposal says the committee will review the documentation immediately.  I think that works only so long as documentation is one of MIT's top priorities.  (Or an adequate number of non-MIT people are involved for whom the Kerberos documentation is a priority.)  But come the next big deadline, I could see doc updates getting put off.  Looking at it another way: I think the prioritization and scheduling of the doc work will happen as with any other work.  Documenting it as happening differently in the proposal won't make it so.

Ken