EXACTLY!
Charles From: owner-openssl-us...@openssl.org [mailto:owner-openssl-us...@openssl.org] On Behalf Of Sanford Staab Sent: Tuesday, November 13, 2012 12:53 PM To: openssl-users@openssl.org Subject: Re: I can't believe how much this sucks Couldn’t agree more Ted. I think the bar on open-source product documentation has been going way up over time. If I were these guys, I’d get it right so I wouldn’t have to keep bothering to answer so many questions over and over. From: Ted Byers <mailto:r.ted.by...@gmail.com> Sent: Tuesday, November 13, 2012 2:49 PM To: openssl-users@openssl.org Subject: Re: I can't believe how much this sucks On Tue, Nov 13, 2012 at 2:02 PM, Lee Fisher <blib...@gmail.com> wrote: For things that the peer support forum and the existing documentation don't cover, you have the source code, which is definitive. Additionally, there are professional OpenSSL consultants you can use for help. It would be more productive to submit bugs and patches, instead of a litany :-) Even so, some of those closely involved in the project ought to be doing a better job of documenting the product. Telling people to hire consultants is even worse than telling people to read the code. I develop software for a living, and I would be ashamed of any attempt to release even one of my products without a proper reference manual, complete design documentation, including a reasonable suite of UML documents (in the case of an open source product since good coders benefit from good design documentation - which, admittedly, I have not produced) and a thorough tutorial. I have had feedback on some of my products that the end users found my interface so intuitive that they did not look at the documentation I'd provided even once, but I do not see that as an excuse for not producing proper documentation. In my view, the documentation for a product is as much a part of the product as the code in the product. The product is not ready for release until the documentation is as complete and polished as is the code. Peer support is hardly a good, or cost effective, substitute for good documentation; and contrary to what some coders I have met, and worked with, have claimed, the source code is often not adequate documentation. Yes, you see what the code is doing, but tracing execution paths through it can be a tedious nightmare; especially if the coder that produced it wrote the code as a candidate for an obfuscated coding contest (something, BTW, I would regard as grounds for dismissal if obfuscation is the only justification the code can offer for it). In my own coding, the only libraries I use often are those that are well documented. Life is just too short to waste on libraries that are poorly documented (unless someone wants to pay me to do so - but they'd be paying a significant premium for such a tedious, and usually frustrating, task). I am not criticising the documentation for openssl, and will not; but I would encourage those who are responsible for maintaining and improving openssl to not neglect the documentation. It would be a mistake to leave that for someone else to do, for when that happens, it is certain that the documentation will suffer. just my $0.02, as a coder with decades of coding experience. Cheers Ted
