On Wed, Jul 13, 2022 at 06:45:48PM +0200, Dirk Stöcker wrote: > The openssl documentation may be logical for someone who knows all the > parts and how they work together, but for everybody else it's a large > glob of isolated files which you simply can't bring together. You have > pages which sometimes describe dozens of functions which seldom have > examples and at least for me they don't help. > > My initial TLS implementation took me days (although I do nothing except > loading the parameters (key,cert,chain) and setup the stuff). Mostly I > only got that done looking at the openssl tools and how they do it. AFTER > you know how the code looks like the documentation helps but not to > getting to this state. Essentially for me the documentation thus always > was only a means to verify that the examples I used actually are correct > and not written by somebody who also doesn't understand it. This sounds like trying to build something given a Reference Manual but no Programmer's Guide. The Reference Manual describes each function, data structure, and file format in full detail. It's essential for understanding individual operations but says nothing about orchestrating them to perform higher-level tasks. It's just a complete list of fully-described features. As you said, this is where you go to understand code that already exists or that you have already designed and are writing now. The Programmer's Guide discusses the logical organization of the package, how typical higher-level tasks might use individual features of the package in sequence, which features go together, which are similar but distinct, and generally what are good ways to think about working with the product. IOW it describes many common things that you can accomplish using those features. This is where you go for basic understanding of how to organize a new design in terms of the available features of the package. A developer who is not already working with the product on a daily basis will probably start in the Programmer's Guide when creating a new design, and have both open when coding. That's my experience, anyway. One more familiar with the package will have less need for the Guide, but it never becomes entirely unnecessary. These two ways of thinking about a product are complementary, and a developer shifts between these modes of thought often while working. I agree that a Migration Guide will, after a brief discussion of the high-level differences between old and new, consist mostly of "if you did task T that way before, now you should do it something like this" for many values of T drawn from the Programmer's Guide. -- Mark H. Wood Lead Technology Analyst University Library Indiana University - Purdue University Indianapolis 755 W. Michigan Street Indianapolis, IN 46202 317-274-0749 www.ulib.iupui.edu
Attachment:
signature.asc
Description: PGP signature
