You are confusing goals and desires. Someone who wants documentation beyond what they have can either (a) write it themselves, (b) wait, (c) offer a bounty. (c) is the only practical choice, if they have money but neither time, nor expertise.
Someone who wants to produce open source code to solve a problem and share the solution will do the least to get the job done. Someone who wants to produce open source software to INFLUENCE others to use it will try to produce the most usable software they can. I submit most open source projects fall somewhere in the middle. Finally, the source code IS the only reliable source of documentation (assuming you can trust your compiler, OS, and hardware to do "the right thing"). It isn't the most CONVENIENT, which is why we desire other forms. Should the O'Reilly book be rewritten? Not unless it's truly awful. But, a wiki shouldn't start from scratch. It should draw upon existing documentation and fill in the gaps. Sucks if you don't have those docs (or can't afford the book), but it is the fastest way to "get there from here" because you don't have to start from nothing. The problem with wikis is that they tend to be a large forest of information with little organization. Unless there is some editing effort, it will be little more useful than a FAQ and mailing list archive. -----Original Message----- From: owner-openssl-us...@openssl.org on behalf of Randy Turner Sent: Thu 11/26/2009 11:38 AM To: openssl-users@openssl.org Subject: Re: General question about documentation That's a great idea Mark and Will, I would be happy to contribute anything that I learn about the toolkit. There have been a wide range of comments from people saying "look at the code" all the way to basically suggesting an attempt at a new version of the O'Reilly book. I can't imagine anyone with any experience at all in software development suggesting that the only source of documentation be the source code. And I don't think I was suggesting that the OpenSSL team necessarily write a new version of the O'Reilly book. Someone also said that if we wanted documentation we should pay for it - which seems counter to the whole open source effort. I'm assuming that the OpenSSL developers are not spending all this time working on the toolkit for the hell of it - I would think they would like as many people to use it as possible, and with that goal in mind, I think the 1.0 release (when it comes out of beta) would be a good stopping point to re-visit the documentation set and providing examples that reflect the most common use-cases. The mailing list is always here for unusual use-cases. That being said, I think a Wiki is also a great idea, but would not obviate the need for the developers of the toolkit to complete the documentation set. I've spent a quite a bit of time with OpenSSL and would be happy to contribute to a Wiki. Thanks!! Randy On Nov 25, 2009, at 3:13 PM, Will Bickford wrote: > IMO a wiki would be a great resource for both developers and users of > OpenSSL. > > Something along the lines of the Subversion Book - an online reference > "book" for OpenSSL. > > --Will > >> -----Original Message----- >> From: owner-openssl-us...@openssl.org >> [mailto:owner-openssl-us...@openssl.org] On Behalf Of Mark >> Sent: Wednesday, November 25, 2009 3:27 AM >> To: openssl-users@openssl.org >> Subject: RE: General question about documentation >> >>> I would like to post a general observation regarding users of the >>> OpenSSL toolkit. >> >> [snip stuff about documentation]] >> >> A long time ago it was suggested to use a wiki for this >> purpose. Can this idea be resurrected? >> >> Mark. >> >> ______________________________________________________________________ >> OpenSSL Project http://www.openssl.org >> User Support Mailing List openssl-users@openssl.org >> Automated List Manager majord...@openssl.org >> >> > ______________________________________________________________________ > OpenSSL Project http://www.openssl.org > User Support Mailing List openssl-users@openssl.org > Automated List Manager majord...@openssl.org > ______________________________________________________________________ OpenSSL Project http://www.openssl.org User Support Mailing List openssl-users@openssl.org Automated List Manager majord...@openssl.org
