It tends to be a shortcoming of many, many types of software documentation that it is feature-oriented rather than task-oriented. That is, it does a good job of saying "this switch does this, that parm specfies that" and a poor job of answering the question "I want to accomplish X. What the heck do I do?" Examples are good, but they are not the only, and perhaps not the best, way of presenting task-oriented documentation. (The trouble with an example is one sometimes finds oneself asking "do I HAVE to do it that way, or did that writer just CHOOSE to do it that way?")
Charles From: owner-openssl-us...@openssl.org [mailto:owner-openssl-us...@openssl.org] On Behalf Of John Zavgren Sent: Monday, November 19, 2012 6:45 AM To: openssl-users@openssl.org Subject: Re: I can't believe how much this sucks Thomas: You make very good suggestions. Of them all (aside from the use of tact in approaching the developers :-) ), I think that easy-to-follow code examples would improve the openSSL experience more than anything else you identify. These examples could even provide a natural context for the "cookbook usage examples", and then we'd achieve two of your objectives. I can recall situations where I had to incorporate a cartographic calculation in code I was writing, e.g., compute a signature, and was unable to find any examples, and the man pages were a poor starting point. They are good for learning the individual library procedures, but they aren't good for pulling them together to create a working software module. (In fact, when I needed to learn how to compute a signature, I downloaded the openVPN source code and read it.) So, what is a list of easy-to-follow code examples? Here are some suggestions: 1.) read private key and a message from a file: encrypt message with private key, write encrypted buffer to (another) file. 2.) read cert and private key, read file, compute signature, etc. 3.) read file, read signature, read ca certs, validate signature. 4.) Example 3 + check CRL. 5.) Example 3 + check with OCSP responder. ??? I'm sure there are a LOT of CA related examples that would help, because I find the creation of a CA to be one of the more painful exercises. On Sun, Nov 18, 2012 at 11:19 PM, Thomas J. Hruska <shineli...@shininglightpro.com> wrote: 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 -- No amount of believing makes something a fact. James Randi John Zavgren 603-371-0513 (home) 603-801-2094 (cell) johnzavgren (skype) 603-821-0904 (skype) j...@zavgren.com
