Kerberos documentation relay

[Zhanna Tsitkova]

Hello,

For some time now we are talking about the lack of Kerberos interface   
documentation. In the past  few attempts were made to fix the  
situation but, unfortunately, for the various reasons they were not  
very successful.

Would you agree that  this problem should be addressed sooner rather   
than later?  The scope of the task and the availability of the    
resources suggest that it should  have procedure,  be spread across  
1-2  years (am I too optimistic?), and, most  importantly, have  
resources, aka volunteers.

As a discussion starter, I would like to bring to the table  few   
points in no particular order:

1. We have roughly 300 functions to document. Where to start with the   
documentation? Perhaps, divide APIs into the groups from most-urgent,  
most-important to least-important. Or by functionality. Or just let  
people to create and  document the set of functions they are  
interested in. One should notice, that for all newly created APIs  
(starting from 2009) we require them to be documented. Also, some of  
the descriptions may be borrows from the other sites (if permitted).

2. The procedure.  The administrator/manager creates and monitors a  
pool of the  undocumented or poorly documented API/ABIs  The writer  
picks up a function  from the pool, creates the documentation and  
sends it to "the  committee" (~ 3 people) . Upon review (it must be  
done without any delay), and if it  was successful, the document is  
proof checked and is placed on the web. Otherwise, either  the initial  
writer or the alternate may update the document and re-submit it  to  
the committee again.

3. Logistics.
   -  Who will host the database.  -  MIT?
   -  Database.  -  sqlite?
   -  How website should look like. - google-style?   It would be  
useful to know what is your favorite site documentation-style wise.

4. Write permissions. Should the updates be committed by the member  
of  the committee only?  Or the original writer should have a write  
access  too.

5. Documentation and code cross-reference. Is it necessary to have it  
cross-referenced? Perhaps having the text of the website only is enough.

6. The document should consist of
   - the interface-name,
   - input/output  description,
   - the purpose of the function text
   - examples of usage (when applicable)
   - "see also" section for the related functionality


If there is an interest and goodwill in the krbdev community to commit  
to such undertake, please, let us know.


As always your input, comments and recommendations are greatly  
appreciated.

Thanks,
Zhanna

Zhanna Tsitkova
tsitkova at mit.edu