Juju secrets documentation lacks detail and is misleading in some places

[DnPlas]

The docs around juju secrets are lacking some details and information that is relevant for using them, specially when integrating with charms. Here are some of the things I have run into while trying to integrate juju secrets with a charm:

1. How to integrate user secrets with charms - While there are some WARNING messages in How to manage secrets telling users that "For the application to be able to use the secret, it needs to be configured with the secret URI. " is not enough to set a clear view of how to actually integrate with a charm. In ssl-key and ssl-crt removal broke compatibility with a specific TLS use case canonical/istio-operators#380 (comment) @jameinel gave an example of how to use user secrets in a charm, specifying details about the things a charm MUST have before a secret can be used. I think this information is not obvious and could be of great help to have it in the docs.
2. Secret events from user secrets - I don't think we have any documentation explaining how a charm that wants to use a user secret can subscribe to Secret Events. It is sort of related to the implementation details sated above, but I think a nice explanation that says what has to happen before a charm can subscribe to those events is really important, specially since this events are not triggered from commands like juju grant-secret <secret-name> <application-name>, contrasting to the behaviour of juju relate or juju config.
3. Secret events - The Secret events trigger section in the Secret events docs may be confusing if no details are given about these events triggers. I think a good addition to this information would be to describe how events are triggered, i.e. what has to happen for the charm to be able to observe user or charm owned secrets.
4. Add secrets to a charm - For someone who is not familiar with juju secrets, finding out that this guide How to add secrets to a charm is the only one that explains how to add secrets to a charm can lead to a lot of confusion, as it is limited to one use case for using secrets. I think it would be nice to have different guides for different use cases as stated previously and perhaps change the title to avoid thinking this is the only way to add secrets to a charm.