An OpenSSL cookbook, where and how?

[Matt Caswell]

On 07/03/2020 09:01, Richard Levitte wrote:
> As part of a documentation effort, more specifically in some
> discussions in https://github.com/openssl/openssl/pull/11220 (exact
> references below), I've floated the idea that bigger coding examples
> should be placed into a cookbook.
> 
> My reasoning for this is very simple: example code in reference
> manuals should be kept minimal and focused on the functions documented
> in that same page.  Anything that start involving too much other
> functions becomes a distraction, or will leave you wondering why the
> example is in *this* page and not *the other page* that describes
> those other functions.  In my mind, this is education 101.
> 
> However, it's true that people may want to see more complete examples,
> where the interaction between different sets of functions is on
> display, and could serve as code to pick and use, more than the quick
> minimalistic examples.  A cookbook.
> 
> So if we should do this, where do we want that cookbook?  Who keeps it
> up to date, and how?  https://wiki.openssl.org/ could be one answer,
> but is it the answer we want?

I agree we do need to provide this broader "how to" type documentation.
It's a major failing of our current documentation that we don't provide it.

Both the wiki and ossl-book were previous attempts where we've tried to
collect this kind of information in one place.

IMO, for now, the wiki is the best place to put this kind of thing. In
the long term I still dream of getting ossl-book off the ground.


Matt