The problem is that the documentation may not be correct, sending your coders on a wild goose chase. Think of the source code as a safe but boring investment (with little barrier to entry), and the documentation as one with high potential yield (with a high barrier to entry) but significant risk of errors. Now, go balance your software portfolio for whatever risk/reward ratio you find optimal. Remember, many code for their own benefit, but documentation benefits others (mostly), so it's hard to encourage high quality documentation without paying for it.
________________________________ From: owner-openssl-us...@openssl.org on behalf of Randy Turner Sent: Tue 12/1/2009 2:08 PM To: openssl-users@openssl.org Subject: Re: General question about documentation As an investor, I would rather have my coders use a product with documentation to "make progress" on the actual goals of the product, rather than reverse-engineer the information they're trying to look for. With the former method, my cost is (n), with the latter method, my cost could be unbounded, depending upon how complex the source code is (i.e., explicit code, or 14 levels of indirection and C macros that have to be understood). It sounds like you're making the case for documentation to me....and I agree. Randy On Dec 1, 2009, at 2:01 PM, Graham Leggett wrote: > Kenneth Goldman wrote: > >> 1 - Reading the source is only as reliable as the skill of the reader and >> the comments in the code. I'd rather have the answers than a research >> project. > > So would I. But far too often, in code of all kinds, this documentation > doesn't exist. As an investor I would far rather have my coders reverse > engineer the code and make it work, than be faced with no information, > and have code doomed to be thrown away. > >> 2 - If I read the source, I can't determine which functions are stable >> and intended to be used by applications and which are internal and >> subject to change or deletion with every release. > > This is only a problem if the developers of the library haven't packaged > their library properly, something that one doesn't expect to still see > in 2009. > > Regards, > Graham > -- > > ______________________________________________________________________ > OpenSSL Project http://www.openssl.org > <http://www.openssl.org/> > User Support Mailing List openssl-users@openssl.org > Automated List Manager majord...@openssl.org > ______________________________________________________________________ OpenSSL Project http://www.openssl.org <http://www.openssl.org/> User Support Mailing List openssl-users@openssl.org Automated List Manager majord...@openssl.org
<<winmail.dat>>
