Hacker News Reader

Comment by ivl | Hacker News Reader

You're not wrong, but there's a big middleground here. To a user without some curiosity this:

  LibreSSL releases contain several parts:

  libcrypto: a library of cryptography fundamentals

  libssl: a TLS library

  libtls: a new TLS library, designed to make it easier to write foolproof applications

  Various utilities such as openssl(1), nc(1), and ocspcheck(8).

With libcrypto, libssl, libtls, openssl, nc, and ocspcheck all links pointing to man.openbsd.org/x does not scream documentation. The words 'documentation' or 'manual' appear nowhere on the libressl home page.

They are undoubtedly present, but unless you click around assuming those aren't links to individual components, you wouldn't think so at a glance.

View on HN

So what your saying the issue is libressl should put a link to the documentation on their front page?

Sounds like a fair request. Perhaps someone should send them an email to let them know.

That being said, you put a finger on the main issue most security and privacy tool have: user friendliness.

In many ways user friendliness corresponds directly with real life security level. Lots of compromises aren't due to a deficiency in the code, but someone using it incorrectly. Maybe by assuming the defaults are sane, or not understanding the implications of some of the technical jargon in the manual.

Remember Sony, a 60 billion dollar company, completely fubared the DRM on the Playstation 2 because a developer didn't understand what an IV is. And you go through the OpenSSL docs and it will tell you where to supply your IV without ever explaining what it is. All it needs is a single paragraph explaining the best practices, probably 5 or 10 lines in the manual.

It _is_ linked to in their front page. The article is complaining about not finding documentation for the openssl command while literally linking to the front page that contains a link to said the documentation. They don't even have to Google, just read!

Unfamiliar people might not realize openssl(1) is linking to the manual page for openssl, or that it's in section one of the manual, thus the (1).

I do think it would be a good idea for the libressl.org site to put a link on the left "sidebar" with the text "Documentation" (which shows a page of links at minimum), just to make it obvious where to find it.

That was the first thing I looked for, and it took me a while to realize that the links "libcrypto", "libssl", etc on the main page were links to the documentation for each command. In fact, the only reason I found them was the fact that your post said "It _is_ linked to in their front page.", so I went back to find them.

Yeah, if I'd needed it right now, I would have figured it out eventually, but I think making it a bit more explicit (for lack of a better term) would be a good thing.

Not just read. There are 23 or so links on that page, roughly one-fourth of which lead to documentation pages, non-obviously. Of course, anything is obvious once you know it, but clearly it isn't obvious enough, or we wouldn't be having this discussion!

So they don't have to search, just read and click on links until they hit one that looks like a man page.

I found it strange since OpenBSD is known for their excellent docs. So after opening the libressl site they have that paragraph stating the parts of the lib and links to their docs. That page works as the documentation index.

Namely

https://man.openbsd.org/openssl.1

Which the author was complaining about needing to use google for. Specifically the https://man.openbsd.org/openssl.1#GENRSA seems well document.

Forks are just the way open source works and if documentation could be better then we are all free to contribute to it.

They're rather working on the assumption that readers know that anything with a "(1)" or an "(8)" after it is a reference to a user manual. This is a very common thing in BSD doco, and in Unix doco more generally.

For experienced Unix users this is likely to be true. It's something that one just learns. For novice users, it is less likely.

Why would a novice would care? Why would a novice interact with OpenSSL anyway?

Reply on news.ycombinator.com