On Tue, Nov 13, 2012 at 3:18 PM, alan buxey <a.l.m.bu...@lboro.ac.uk> wrote:
> Hi, > > > 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 > > it is an Open Source project - thus there is also an onus on the USERS who > use the code > to also provide something into the mix - commonly that is for > documentation - as > users are often not the ones maintaining or improving the codebase...but > are people > USING the API and software (usually for their own purposes and financial > gain) - so ideal > for being people to offer something back in the way of , eg, better > documentation. > > Nonsense. The most the users can be expected to contribute is their questions. That is where the fodder for FAQs comes from. From the perspective of a library writer, they also show what you've missed. I am CTO in my company, and when I direct a junior or intermediate programmer to use library X (which may well be one I have developed over the decades), I do not tell them to study the code to figure out how to use it. In many cases, the library details involve aspects of the problem at hand that are well beyond their experience. However, when I give them direction to use the library, I also point them to good quality user documentation: documentation that clearly llustrates how the library is properly used, and it is at a level that they can understand. in this way, I can educate them, or introduce them, to technologies that are new to them at a pace they can handle, and that without wasting time examining the details fo the library implementation code which, as I said, is often well beyond what their experience can handle. > I'd cite a use example - eg Cisco use OpenSSL for their AnyConnect SSL > client - they are > using quite a few of the APIs and functions in their commercial product(s) > - a proper > symbiotic relationship would be for their expertise to be fed back in the > way of > bug fixes and documentation. > > coders are often NOT the best documentation writers ;-) > > Nonsense. No-one knows better how the code ought to be working than the folk who developed it. I begin with the assumption that all my coders are functionally literate. I expect them to document their own code as part of the duties for their position. Of course, the senior staff will review, and require edits, as part of the routine code reviews; and, on a large project, there may be a professional educator who takes responsibility for the final drafts of the user documentation. But there is no excuse for a coder not to document his own code. And that a given product is open source, or free, is not an excuse for library developers doing a poor job documenting their product. Take a look at the boost documentation. Some of that is great; and some not so much. But the boost library documentation is gnerally more than enough for a capable programmer to make good use of most of those libraries. Granted, though, some of those libraries are sufficiently advanced that I would only ask senior members of my team to make use of them. And there are other open source products that do have adequate to good documentation; at least if you look carefully. Cheers Ted
