Kerberos documentation relay
tsitkova at MIT.EDU
Thu Jul 22 11:18:32 EDT 2010
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
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.
- 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
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
tsitkova at mit.edu
More information about the krbdev