Update odc-stac documentation to be more accessible to users

[caitlinadams]

This ticket is about beginning the process of updating our documentation, and understanding how we might start to tackle it. The goal is to complete a select number of minor updates to the odc-stac read the docs to understand how we want to communicate information. This can then be developed into a set of principles we can take forward into updating other documentation.

To complete this card, we should

• Review the Diataxis framework for documentation
• First pass of how elements of the current docs map to the framework
• From the above list, design one tutorial, one how-to-guide, one explanation, and one reference example to work on
• Complete tutorial example. Note any learnings
• Complete how-to-guide example. Note any learnings
• Complete explanation example. Note any learnings
• Complete reference example. Note any learnings
• Promote improvements to documentation and ask for feedback
• Identify next set of ideas for improvement

[caitlinadams]

@robbibt @woodcockr -- what do you think of this as a start?

@robbibt -- if you're interested, maybe we can work together on tick box 2 and 3 once you've had a chance to review the framework.

[woodcockr]

The Diataxis framework made for an interesting read, not seen that before.
On the whole sounds like a good place to start though I think we need something along the lines of an explanation as to the odc ecosystem and where odc-stac sits in it to give context (and the thorny issue of work-in-progress like odc-geo, which odc-stac uses, was lifted and refactored from datacube-core and is yet to be incorporated back). of course odc-stac can be considered in isolation, it's just given its part of ODC ecosystem we should expect people wanting to understand where it fits and satisfy that curiosity.
A little context will be helpful to writing the odc-stac docs.

[robbibt]

Hey @caitlinadams, finally got around to this! Diataxis was super interesting; have shared it within DEA too because I think it's very relevant to our DEA Notebooks/user guide work. I think "Explanation" is the trickiest section to me - obviously super important, but I think my usual way of doing this kind of thing is to integrate explanations throughout tutorials and how-tos themselves, rather than thinking of it as something discrete. I agree with @woodcockr that explanations of how ODC-stac fits into the datacube universe is super important though, and I could definitely see how that could fit at the top of the docs to provide context for the more technical guides to follow.

I'll try and find some time next week to go through the current ODC-stac docs in more detail to set up for 2+3!

[robbibt]

As far as I know, these are the main existing ODC STAC material we have across different platforms/websites. All should be CCBY4.0 so suitable for copying/modifying/editing!

DEA

• https://docs.dea.ga.gov.au/setup/gis/stac.html
• https://docs.dea.ga.gov.au/notebooks/Frequently_used_code/Downloading_data_with_STAC.html

DEAfrica

• https://docs.digitalearthafrica.org/platform_tools/odc_stac.html
• https://docs.digitalearthafrica.org/sandbox/notebooks/Frequently_used_code/Downloading_data_with_STAC.html

ODC STAC repo

• https://odc-stac.readthedocs.io/en/latest/notebooks/stac-load-e84-aws.html
• https://odc-stac.readthedocs.io/en/latest/notebooks/stac-load-S2-ms.html
• https://odc-stac.readthedocs.io/en/latest/notebooks/stac-load-S2-deafrica.html

[Kirill888]

And one more here:

https://odc-stac-demo.netlify.app/

[Kirill888]

Relevant here:

opendatacube/odc-stac#95