I like OpenSSL, I want to learn how to use it, and I would love to
get involved in writing some technical documentation so that I could
learn more quickly. I just need to work with someone that actually
*knows* the library.
"Mark H. Wood" wrote:
>
> I ought to stay out of this, but...
>
> On Thu, 23 Dec 1999, Leland V. Lammert wrote:
> [quote snipped]
> > I don't think you have placed OpenSSL in the proper perspective. OpenSSL
> > is a *toolkit* used primarily with OTHER applications. For example,
> > Apache has at least three different ways to integrate OpenSSL, and the
> > docs for that are contained within the various Apache modules/options.
> > OpenSSL is a VERY useful toolkit, .. to use it you only need (basically)
> > three things: 1) How to download it; 2) Compile it; 3) Generate a
> > certificate. All are covered pretty completely in the docs.
>
> So generating one certificate is the only thing that the OpenSSL package
> can do? It sure looks like it can do a whole lot more, but how does one
> begin thinking about using those capabilities?
>
> > As a toolkit, OpenSSL can only be used *directly* by a programmer that
> > knows C/C++, and in that case documentation is not required, as the
> > programmer has the experience to use the toolkit directly.
>
> How did the programmer get this experience in using an API before he has
> used it?
>
> > Would you complain that gcc does not have documentation?
>
> Actually I do. There is a lot of documentation, but (for example) there
> is no document that describes the entire language that gcc recognizes.
> The gcc doco. mainly describes things that are unique to gcc, and spends a
> lot of its space on porting issues. It's more like an internal design
> document than something for end users. Since I'm already getting more
> than I paid for, I don't complain loudly or often.
>
> IMHO a really well-documented toolkit provides at least two documents: a
> Reference Manual that completely describes the syntax and semantics of the
> language, APIs, or whatever embodied in the package, and a Programmer's
> Guide that describes the kit's relationship with the outside world. Look
> at the O'Reilly X Window series, for example: each layer is represented
> by a pair of (rather thick) books. One book specifies the function calls,
> in alphabetical order; the other shows how they work together, describes
> the higher-level structure of the layer, and places the whole mess in
> context.
>
> Writing a good Reference Manual is hard work. Writing a good Programmer's
> Guide is extraordinarily hard work. It would be easy to say, "well, then,
> go ahead and write the books, and we'll thank you." But this requires
> detailed knowledge of the package, which is what people are wanting in the
> first place. In a proprietary project, someone would be assigned to hound
> the programmers for details and write them up in the appropriate corporate
> style, but that won't happen in Open Source because there is no PHB to
> make it happen.
>
> This will probably be a permanent weakness of Open Source products, sadly.
> The documentation will usually wind up being written by people who would
> much rather be designing code, and so it will be shorter and thinner than
> that which is desired by other developers wanting to build on it. It's
> hard to know how much detail is enough, when you've lived inside the
> product every day for months on end.
>
> --
> Mark H. Wood, Lead System Programmer [EMAIL PROTECTED]
> "Where's the kaboom? There was supposed to be an Earth-shattering kaboom!"
> -- Marvin Martian, 01/01/2000 00:00:00
>
> ______________________________________________________________________
> OpenSSL Project http://www.openssl.org
> User Support Mailing List [EMAIL PROTECTED]
> Automated List Manager [EMAIL PROTECTED]
--
North Shore Technologies Corporation - Steven J. Sobol, President & Head
Geek
815 Superior Avenue #610, Cleveland, Ohio 44114, USA Phone +1
888.480.4NET
[EMAIL PROTECTED]
http://NorthShoreTechnologies.net
Owned and loved by the dogs of Jaymist Chinese Shar-Pei, Montville,
Ohio :)
Alcohol and calculus don't mix.. Never drink and derive.
______________________________________________________________________
OpenSSL Project http://www.openssl.org
User Support Mailing List [EMAIL PROTECTED]
Automated List Manager [EMAIL PROTECTED]
