Storage documentation is incomplete and confusing

[jacekn]

I read storage documentation here:
https://jujucharms.com/docs/1.25/storage

and I found it confusing and incomplete. It's hard for me to say exactly what's wrong but some random things I spotted:

1. There are no good examples for charm authors. It's very unclear how metadata.yaml should look like for any but the most simple scenarios.
2. The docs list "juju storage add" (adds unit storage dynamically) but then say it's only possible to add storage during initial deployment
3. It's very unclear how to write a charm that support multiple storage types (for example local for dev, block for prod)
4. I'm not sure if it's just docs or juju itself but I could not get "storage-get" to work anywhere but in -storage- hooks

[evilnick]

This is superceded by changes in the way storage works for 2.x