On 11/13/2012 11:34 AM, Sanford Staab wrote:
I have been struggling with openssl for a few months now writing batch scripts
on windows trying to make a .net web client with a client certificate work with
2-way ssl against an apache web server.
Do you guys just want to continue to answer questions on this alias and not FIX
the docs somewhat over time? I could go into a litany of how much information
is just missing from the docs with INCOMPLETE everywhere. (see this link for
one of the 900k+ hits on a google search of “openssl+docs+suck” for how much
hell you guys are putting people through trying to figure out this tool)
openssl is used all over the world by tons of people (so I feel dumb having
problems here – but I know from Google I am not alone.) but it is just
unbelievable to me that the docs remain so terse and useless for so many years.
I have sent email to this alias previously asking how I can help with this. It
seems to me there should be an openssl docs forum where content from this
eventually finds its way into the online docs themselves.
A tool is only as good as people are able to use it.
The OpenSSL dev team consists of fairly old-school *NIX folks. It is a
low-level library and certificate generation and manipulation tool that
has gained significant notoriety for its reliability, stability, and
security.
The primary documentation is manpages. This is an outdated method of
documenting software and, as I've found, the primary source of many
complaints. In this regard, it is time to move on. I can't remember
the last time I had to fire up 'man'. I'm much more apt to just run a
Google search.
Given my experience with end-users of this product, I've come to the
conclusion that there are three distinct forms of documentation needed
for OpenSSL:
- API documentation. This is already fairly complete but hard to find
everything and needs someone to go over it and update it. Areas that
are entirely missing need to be fleshed out. It is also time to
consider an alternative format to the traditional manpage.
- Cookbook usage examples. 'openssl' command-line commands to
accomplish common tasks in a cookbook format. I can point people to
third-party sites (madboa comes to mind). However this sort of thing
should really be on the OpenSSL website.
- Complete, easy-to-follow code examples for a variety of common
programming tasks. There are the test programs, but I view those more
for testing the library for consistency against itself than
demonstration on how to code against the library. There's a difference.
The OpenSSL website should always have the definitive collection in a
copy-and-paste ready format. Also, OpenSSL is used within a variety of
programming languages. Examples and integration by language would be
ideal. Pick the top three to five languages that cause the most churn
on this list (C# comes to mind as #1).
It is approaching six months since the last OpenSSL update. We're
probably due for a new set of source releases any time now. So now is
the ideal time to talk it up about getting "better documentation" on the
dev team's schedule while they begin the planning stages of the next
release. If you succeed at this, you'll be my hero of the month because
I've been wanting this for ages. You might want to approach the devs
though with a little more respect/tact. Saying the documentation
"sucks" is a great way to get ignored. Their time is valuable.
--
Thomas Hruska
Shining Light Productions
Home of BMP2AVI and Win32 OpenSSL.
http://www.slproweb.com/
______________________________________________________________________
OpenSSL Project http://www.openssl.org
User Support Mailing List openssl-users@openssl.org
Automated List Manager majord...@openssl.org
