(Just came back from hiking in the Harz mountains late yesterday evening.)
On Fri, Oct 20, 2000 at 12:37:08PM -0700, john traenky wrote:
> I read you too work on documentation. I would like to
> join the work. How should I start? Should I gather
> notes about SSLeay and OpenSSL and create a user guide
> draft? Who in the group reviews and approves such
> writing? I'm eager to start and have experience as a
> technical writer & editor. I also have the world's
> worst German imaginable, easily worse than any
> Berliner. Or Muenchener, depending on your location.
Berlin is a perfect guess :-)
These are a lot of more or less difficult questions, I'll try to sort out
things:
- There is an OpenSSL developers team that has access to the CVS source code
archive and that finally decides on what goes into OpenSSL and what not.
The way the team is gathered is nowhere defined. At some points in time
people were added.
- Contributions to OpenSSL are always welcome. They should be sent to
[EMAIL PROTECTED] and should be in "diff -u" format. The developers
will pick them up and include them into the package. Sometimes it seems
such postings will simply pass by, then you have to send some reminder :-).
- This scheme does not really apply to documentation, if it is in the large
scale. From time to time I submit manual pages for the SSL_* functions.
I have spend some time while writing Postfix/TLS to figure things out
and want to make it possible for other people to share my knowledge.
This is not my main job, so my contributions are coming in slow, but
in the long run I should be able to document all of the SSL_* functions,
maybe before the release of 0.9.7 (won't happen to soon probably).
- What is really missing for OpenSSL is a "User's Guide" (as opposed to the
"User's Reference and Manual Pages" we currently have.
This User's Guide would contain the concepts, things like memory management,
the concept of session caching, the structure of the SSL-setup (an SSL
machine using BIO's for the actual input/output). This Guide would help
people to understand how OpenSSL works and enable them to start writing
their own applications.
Today we have or are working on documentation on the "analysis" part.
You can look into a TLS/SSL application, then look up the functions used
in the reference manual/manual pages and understand what they are doing.
A User's Guide would be suitable for the "synthesis" part, enabling people
to realize their own application.
The problem is that realizing this kind of "User's Guide" require a lot of
intimate knowledge about the internals of the OpenSSL library. It is simply
not available at this time. Some information can be collected by following
the links on www.openssl.org, but you will probably have a problem to
describe the concepts unless you have written your own application,
analyzed at least once a TLS session handshake etc.
Probably this job could take you more than just a couple of hours :-)
If you think this would be something you like to do, it would be best
to set up your own website and a link would be added from www.openssl.org.
This way you would keep your complete freedom to change whatever you like
whenever you like. Submitting patches via mail to openssl-dev always includes
a delay. Whenever you think you have completed another package of work,
you can send an announcement to the list. It can than also be added to
the main package.
Other people like Claus Assmann already gave additional hints. Let's see
whether the disussion brings more points.
Best regards,
Lutz
--
Lutz Jaenicke [EMAIL PROTECTED]
BTU Cottbus http://www.aet.TU-Cottbus.DE/personen/jaenicke/
Lehrstuhl Allgemeine Elektrotechnik Tel. +49 355 69-4129
Universitaetsplatz 3-4, D-03044 Cottbus Fax. +49 355 69-4153
______________________________________________________________________
OpenSSL Project http://www.openssl.org
Development Mailing List [EMAIL PROTECTED]
Automated List Manager [EMAIL PROTECTED]
