Documentation improvements - users with no prior crypto experience

[brycx]

In the recent HN thread, there was a comment made about that, even though Orion tries to offer a usable API, it's still not very clear for users with no prior crypto experience. This discussion should serve as a central point, in terms of discussing and finding areas of improvement to the current documentation.

The following are quotes from the comment:

"[..] where would one learn how to use a library like Orion? Eg, if Orion is aimed at easy to use - i'm still not the target audience. But, i do write software that i want to allow users to sign. To encrypt their data at rest. To verify signatures."

"Where would i learn enough to decide how to choose solving my above problems with Orion vs GPG?"

"That's been my biggest problem with crypto. I know enough to know to be wary, but not much beyond that. Choosing tools with that mindset is difficult."

Quoting @vlmutolo, I think this is a pretty good description of what the current issue seems to be:

"Right now, I'd say the state of the library, rather than its intention, is that it's extremely usable for people who pretty much know what they want, and fairly hard for the average developer to misuse."

It seems we need to focus also on providing documentation about what a user wants, in a given situation - not only how. The high-level APIs documentation all contain a section called "Use case" where common use-cases are described. This seems like a good starting point, where we could begin by making these more prominent and easier to spot. Perhaps expanding the wiki with more use case descriptions, linking to relevant API docs, to not turn the actual crate docs into a novel.