please review draft krb5 API reference manual

[Tom Yu]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

The MIT Kerberos Consortium has hired a contract technical writer,
Elizabeth Stone, to improve the krb5 API documentation.  The following
is her review memo outlining the feedback we request on this
documentation.

Please send comments to her at <estone at mit.edu>.

====================

Greetings,

This is a draft of the krb5 API reference manual, written in response to complaints
about the available documentation. The intended audience is Kerberos
application developers with varying degrees of familiarity with Kerberos.

The review release files are in http://web.mit.edu/estone/www/.

- --What does a newbie need to know?
- --If a developer is Kerberizing an existing application, what information
would make it easier?
- --If a new developer is upgrading an application that was Kerberized by someone
else 3 years ago, how can we help them?

No-one wants to read documentation -- they want to get their information and
go back to work. Nothing is obvious to the uninformed -- if you see information
that would only make sense to an experienced Kerberos application developer, mark it.

 In general, review for technical accuracy and completeness.

YOU DO NOT HAVE TO REVIEW THE ENTIRE THING. Let me know what parts you did review, and/or
any topics you are particularly interested in.

DEADLINE: June 25

I need your feedback -- if you can't make the deadline, please let me know when
you can send your review comments.

ABOUT THIS DRAFT

This draft release contains the following files (which can be found at
http://web.mit.edu/estone/www/):

draftkrb5.hin       Annotated header file
KRB5API.doxyfile    Doxyfile, used to generate output from source file
html.zip                        HTML output, generated by the above files

You can generate other output formats. Install doxgen, version 1.5.5 and above,
on your computer and modify the input and output settings in KRB5API.doxyfile.
The output might look REALLY ugly. Please note the glitches and return with
your review comments.

See doxygen.org for information on doxygen.

WHAT TO REVIEW

 --Technical accuracy
 --Completeness (should there be more detail?)
 --Anything marked ??
 --Anything on the ToDo list that isn't marked ers
 --Missing structure, #def, and field descriptions
 --Terminology accuracy and consistency (is the same entity consistently
described by the same term?)

You might find some content redundant -- it's probably intentional, and part of
technical writing style. Comment it if you aren't sure.

Would you find the following things useful?

- --In Introduction, a concise description of the programming model--
or would a link to Kerberos site be enough?
- --A glossary
- --A link to external error code tables
- --Deprecated fcns linked to replacement fcns

WHAT TO IGNORE
 --Consistent format of doxygen comment blocks
 --Grouping and subgrouping in navigation tree
 --Links between #defs, fcn parameter descriptions, and structure field descriptions
 --Consistent typeface formatting. I will be using the following conventions:
    -parameters, flags, and fields in italics
   -#defs, error codes, fcn and structure names in courier font
 --Writing style/grammar of running text
 --Strict adherence to ASN.1 style
 --C++ terminology
 --ToDo items marked ers
 --Glossary entries

REVIEW INPUT
Mark your comments with references to the to fcn, structure, field, etc.
You can use line numbers in the source file if you like.

Please use any Windows-readable format -- flat text is fine.

If you annotate the header file with your comments, please rename it before you send it
back to me.

THANK YOU!
ers

*You might find the following sites useful:*

Kerberos Wiki
http://k5wiki.kerberos.org/

Existing Kerberos documentation,
http://web.mit.edu/kerberos/

Sun (GSS-API)
http://docs.sun.com/app/docs/doc/816-4863

OpenVMS documentation
http://h71000.www7.hp.com/doc/83final/BA554_90008/

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.8 (SunOS)

iEYEARECAAYFAkhZSfcACgkQSO8fWy4vZo6yyQCgqPoBTNXrZtKJ3HsqdegfTA4S
GRgAoN15ay9u1/Awd++G8vnd94Biq6h9
=+VX5
-----END PGP SIGNATURE-----