> WORKING EXAMPLES would be REAL cool. You kind of have it with the source code to openssl.exe.
Crypto++ had the same way back when (its a C++ crypto library, and its not nearly as popular as OpenSSL). Users did not check cryptest.exe for API usage (cryptest.exe is the equivalent of openssl.exe). In addition, it was terse C++ code and hard to understand. We fixed most of the "How do I" questions by adding a wiki and providing code examples. It drastically reduced the number of questions. When there is a question on basic usage, I just provide a link to the wiki. For example: http://www.cryptopp.com/wiki/3des, http://www.cryptopp.com/wiki/Cbc_Mode and http://www.cryptopp.com/wiki/Rsa. As Wei Dai (the author of Crypto++) answers design questions or questions that require insight, I make sure it goes in the wiki for those who RTFM. For example at http://www.cryptopp.com/wiki/Elliptic_Curve_Cryptography: "Taking from Wei Dai on the Crypto++ mailing list: To minimize the size of public and private keys, what you need to do is encode only the private exponent of the private key, and the public point of the public key." We then provide a code sample. The wiki started out bad - it was sloppy and incomplete. Over time, the crowd converged on the right answer. Its a property of the crowd. Jeff On Thu, Nov 15, 2012 at 9:52 AM, Sanford Staab(Gmail) <sanfo...@gmail.com> wrote: > In the case of openssl, a big gain would be to simply document the command > line interface better and create a doc centric forum for people to add their > lessons learned filed around the particular feature area of openssl. WORKING > EXAMPLES would be REAL cool. Does anyone on this alias want to let me or > others know how we can update the docs somehow? > > -----Original Message----- From: Carlo Wood > Sent: Thursday, November 15, 2012 8:31 AM > To: openssl-users@openssl.org > Subject: Re: I can't believe how much this sucks > > > On Tue, 13 Nov 2012 14:11:17 -0700 > t...@terralogic.net wrote: >> >> This is just a NORMAL way for a programmer to work IMHO. I HATE >> comming into undocumented code years after its been written and IMHO >> its a big booby trap because its very easy to miss something and that >> creates hard to find bugs. Really criptic error messages don't help >> this. I've looked in the OOS community and there are attempts to put >> together systems and one I looked at was OXYGEN. > > > I concur. When I was 12, I wrote compact code with only single > character variables and no documentation. For some reason I was able to > have thousands of code lines all in my head at once and I had no idea > why I'd need to add documentation. > > When I got older, I started to use more descriptive variable and > function names, mostly for the purpose of being able to > 'grep' (reg.exp) them in large code. At some point I completely did > away with abbreviations and only used complete English words, > discovering that code is incredibly better to understand when the > variable names express exactly what they mean (to the point that it > avoids bugs). I still didn't see the point in documentation however: > the code explained itself as if it was English. > > Only when my memory started to get worse and I couldn't remember > Megabytes of code anymore, especially when my code became so complex > that I had to use Object Orientation because it was impossible to keep > an overview, I started to document code. The funny thing is: I did this > mostly because I knew that a year later I wouldn't be able to > understand it myself anymore if I didn't; not because I thought that > anyone else might need it. > > Now, after more than 30 years of coding experience I have reached the > same conclusion as terra wrote: Code is only as useful as it's > documentation. Don't bother to write code without good COMPLETE > documentation as it's worthless: only you, the developer (with a good > memory on top of that) will think it's trivial and usable. Everyone > else will not be able to use it. > >> >> http://www.stack.nl/~dimitri/doxygen/ >> >> >> I have no idea at this time how useful this would be. >> >> >> Perhaps the best we might be able to do on the user side is a wiki >> and perhaps one exists. >> >> >> I did a google search on this. >> >> https://help.ubuntu.com/community/OpenSSL >> >> ^ I did find this and I did not look very hard. Maybe there is >> something better. If there is then it doesn't come up in the 1st >> hits google finds. >> >> >> So I think we can do much better. >> >> Just my 2 cents. ______________________________________________________________________ OpenSSL Project http://www.openssl.org User Support Mailing List openssl-users@openssl.org Automated List Manager majord...@openssl.org
