The first example I stumbled across of this was Java. The original Java doco was very, very easy to follow. But they invented interfaces, and gradually instead of passing say a string you passed some object that implemented a string like interface. After a while you even just finding out "how do I get me an object with the required interface" was a struggle.
The underlying cause is originally you just have to read and learn the basics of the language and it's core library. Everything else was expressing in terms of that, so if you read the documentation for some library, you already understood the parameters passed and the return results. Then the language gave developers the ability to build their own foundations. After that, when you looked at the documentation for a random library, it's arguments and return values were types you had never seen before - they were all abstract base classes and interfaces. Delve into them, and they also were made up of the same thing. You often had to pick you way through 1000's of definitions before you could get a complete picture.
Today, I'd say OpenSSL is the worst. In it's EVP API even the parameters to functions are abstracted to OSSL_PARAM's, and then they don't document all of them of just refer you to other bits of the data for "defaults", only half of which apply to the function you're trying to use.
I’m considering the possibility of creating a second documentation page to address specific use cases or common questions without disrupting the existing structure. I want to ensure that experienced developers who rely on the current documentation are not confused by any changes.
I plan to reach out to the OpenSSL community this week to gather more insights and feedback. Thank you for pointing me in this direction!
It doesn't have to be that way. Rust is a good example of a language that like Java and OpenSSL is built on lots of abstractions, but nonetheless the doco is a joy to read and follow. A lot of thought has goes into most Rust API's, so that good doco is a product of good API design combined with good document writing.
It will be a challenge to put lipstick on this particular pig - but on behalf of all OpenSSL users out there, I wish you luck.
Otherwise it's an awesome project.
Sure, it might be more work than soliciting user complaints. But opining “your documentation is bad” is unlikely to foster the conditions that actually improve actual documentation for actual projects. Documentation problems are usually the result of effort writing documentation by people highly technically informed about a project, tooling is rounding error.
Good luck.