docs: fix and clarify holistic example of handling storage

[dwilding]

This PR significantly reworks How to manage storage. The current doc has several problems:

• It's not clear that _update_configuration is supposed to be an example of a holistic handler.

• The code incorrectly tries to access self.model.storages["cache"] as an object (it's a list).

• The doc mixes up machine and Kubernetes charms, which require different approaches because of (1) multiple vs singular storage and (2) how & whether to configure the workload with storage instance paths.

• The doc shows how to specify a location in a storage definition and explains the default location that Juju determines. This can mislead charmers into thinking that locations are predictable and could be hard-coded, when actually it's a better practice to transparently accept the locations that Juju determines.

Since this PR is substantial enough already, I've tried to leave the parts about detaching and tests largely unchanged.

Preview of updated doc

See related discussion in https://github.com/canonical/operator/pull/2083

[dwilding]

Thanks @tonyandrewmeyer for reviewing and explaining where the doc is mixing things up. I worked through the doc more carefully and totally agree with you. Also, I find the structure of the doc quite confusing.

I've tried a partial refactoring of the doc, to make it easier to follow and clearly separate the machine and K8s info. There's more that really ought to be improved, but this is enough for one PR I think.

Preview doc

New/reworked sections:

• Manage storage for a machine charm >
  • Define the storage
  • Access the storage
• Manage storage for a Kubernetes charm >
  • Define the storage
  • Access the storage

Other sections are largely untouched.

[benhoyt]

We'll wait to progress this one till David is back as it's not urgent.

[dwilding]

@dimaqq & @tonyandrewmeyer would you mind re-reviewing this one? I've significantly reworked the doc to address fundamental issues, so it would be best to review from scratch if possible. (I've updated the PR description to reflect the new approach)

Thanks a lot, and please take your time - this is not high priority

[tonyandrewmeyer]

@dwilding sorry I've been slow on this - I meant to review before our doc session today, but that's looking unlikely now. I'll definitely do so this week before going into my break.