<instance_image> documentation needs improvement:
1. The url attribute is described only as "The URI of the image asset." Should this really be "The id of an <image> element"?
2. The details section lists 2 behavior options within the paragraph; these should be bulleted for clarity.
3. the details section says "The behavior of instantiating an image is typically straight-forward, except for images that are not renderable." ... And then it tells you nothing at all what to do about those difficult cases! Can we have some hints? Or at least why it's not straight-forward?
4. Also says "If the renderable image is marked as “shared”" ... remove quotes from shared and add "using <renderable share="true" />".
5. The example could be more useful if it showed what the url attribute references. Current example is:
Add before it:
Does this look OK?