> 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. > Just to clarify...
There isn't a debate about whether "source code" is documentation - documentation is something altogether different from source code, and it this altogether different form that is open to debate. I think the layout, and organization of the existing OpenSSL website is evidence enough that the group intended to provide an organized documentation tree - that much is certain, so we can defer the goals/desires semantic discussion. My only point is, I think documentation has taken a back seat "priority-wise" due to other apparently higher-priority development tasks (including possibly paid consulting time). My suggestion is, that we try to find some way to update the documentation on the website to reflect the features and functionality of the 1.0 release. The 1.0 release seems like a natural point at which to revisit how we (the community) or the core developers, or both, can re-sync the documentation sufficient to cover the common use-cases envisioned for the feature-set. Including the basic API docs which make up the bulk of the existing documentation at the site today. I wouldn't necessarily damn the wiki out of the gate, but I agree it will need some organization and possibly editorial support from the core development team, to be sufficiently usable to keep users of the toolkit productive. And I reiterate, as a user of the toolkit, I would be happy to contribute to such a Wiki. Randy On Nov 26, 2009, at 1:15 PM, Rene Hollan wrote: > 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 > >
