Re: An OpenSSL cookbook, where and how?

2020-03-09 Thread 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


Re: An OpenSSL cookbook, where and how?

2020-03-07 Thread Dr Paul Dale
Might the demos be useful for something like this?
I know they aren’t in great state and could do with better documentation but 
they seem to fulfil most of the suggested goals.


Pauli
-- 
Dr Paul Dale | Distinguished Architect | Cryptographic Foundations 
Phone +61 7 3031 7217
Oracle Australia




> On 7 Mar 2020, at 7:03 pm, Richard Levitte  wrote:
> 
> On Sat, 07 Mar 2020 10:01:59 +0100,
> Richard Levitte wrote:
>> 
>> As part of a documentation effort, more specifically in some
>> discussions in 
>> https://urldefense.com/v3/__https://github.com/openssl/openssl/pull/11220__;!!GqivPVa7Brio!IKN_xNCo3Vpfv_o5dvd-lE8BpdsZ0Pbcvjkm1_ee4kyvMZYTfI5w5BmcJuDJ7pw$
>>   (exact
>> references below), I've floated the idea that bigger coding examples
>> should be placed into a cookbook.
> 
> I forgot the references:
> 
> https://urldefense.com/v3/__https://github.com/openssl/openssl/pull/11220*discussion_r386751635__;Iw!!GqivPVa7Brio!IKN_xNCo3Vpfv_o5dvd-lE8BpdsZ0Pbcvjkm1_ee4kyvMZYTfI5w5Bmc3tLgiYQ$
>  
> https://urldefense.com/v3/__https://github.com/openssl/openssl/pull/11220*issuecomment-596060267__;Iw!!GqivPVa7Brio!IKN_xNCo3Vpfv_o5dvd-lE8BpdsZ0Pbcvjkm1_ee4kyvMZYTfI5w5BmcAjPjGdw$
>  
> 
> -- 
> Richard Levitte levi...@openssl.org
> OpenSSL Project 
> https://urldefense.com/v3/__http://www.openssl.org/*levitte/__;fg!!GqivPVa7Brio!IKN_xNCo3Vpfv_o5dvd-lE8BpdsZ0Pbcvjkm1_ee4kyvMZYTfI5w5BmcbK3Tc-Y$
>  



Re: An OpenSSL cookbook, where and how?

2020-03-07 Thread Richard Levitte
On Sat, 07 Mar 2020 10:01:59 +0100,
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.

I forgot the references:

https://github.com/openssl/openssl/pull/11220#discussion_r386751635
https://github.com/openssl/openssl/pull/11220#issuecomment-596060267

-- 
Richard Levitte levi...@openssl.org
OpenSSL Project http://www.openssl.org/~levitte/


An OpenSSL cookbook, where and how?

2020-03-07 Thread Richard Levitte
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?

Thoughts welcome!

Cheers,
Richard

-- 
Richard Levitte levi...@openssl.org
OpenSSL Project http://www.openssl.org/~levitte/