Project direction

[Michael Richardson]

Benjamin Kaduk <kaduk at mit.edu> wrote:
    >> On Mon, 2 Nov 2020 at 10:47, Christian Heinrich <
    >>
    >>
    >> > Maybe we should define the problems that new end users experience
    >> > during onboarding instead and address those first?
    >> >
    >>
    >> Better documentation would help enormously.

    > Would that take the form of ensuring that each public API has a man page,
    > or a general "here's how to get started with <this type of operation>" with
    > examples, or something else?

Most of the APIs have a man page, but the man pages are often not that
useful.  They might explain how to use the call, but not always:
   * why I should use this call?
   * how to get the various inputs for the call.

There are many manpages which explain the {A,B,C,D}_get_{X,Y,Z}() calls.
And while this is a nice convenience, as they are rather similar, the result
lacks much of the context needed above.

I would like a man page for each *object* that OpenSSL has.
Tell me how to make the object, how to free it, how to manipulate it, what
the expected lifetime (to use the Rust term) for the object is.
Please also tell me what it's a pre-requisite for.

The sectional and version organization of the web site is a bit wonky.
We need links from the 0.9.8 version of the man pages to the "most recent",
as the older pages get better Google SEO.

--
]               Never tell me the odds!                 | ipv6 mesh networks [
]   Michael Richardson, Sandelman Software Works        |    IoT architect   [
]     mcr at sandelman.ca  http://www.sandelman.ca/        |   ruby on rails    [

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 487 bytes
Desc: not available
URL: <https://mta.openssl.org/pipermail/openssl-project/attachments/20201102/58e57d35/attachment.sig>