Suggestions for docs: High-level examples of using Rasters.jl with main features from dependencies

[JordiBolibar]

First, thanks a lot for all the work you're putting here!

I'm aware that the documentation is mainly focusing on each separate package, but since Rasters.jl sits at the top of the stack, it would still be nice to have some higher-level examples where Rasters.jl is used in combination of the main features coming from DimensionalData.jl and some of the other main dependencies.

This would provide a more holistic view of a "normal" usage of this package. For geospatial users, one can use Rasters.jl to do anything one would do with DimensionalData.jl, knowing that if any geospatial thing is needed you only need to add the necessary extensions.

I think a specific separate section in the docs on high level "real world" examples, with links to DimensionalData.jl and a clear explanation of the stack and "who does what" would really help.

[tiemvanderdeure]

Do you have an example or use case in mind? I think what is 'normal' use will depend a lot on the user. There are a couple of examples in the docs already that correspond pretty well to some of my normal use cases. But I agree that maybe things like set or just creating a dimension from-scratch aren't so well represented.

[lazarusA]

There is already some places where this could go. Basic usage PRs are welcome 😄 .

[felixcremer]

Maybe we could set up integrated docs like DynamicalSystems.jl https://juliadynamics.github.io/DynamicalSystemsDocs.jl/dynamicalsystems/stable/.

[JordiBolibar]

Basically, what confused me was that I was using Rasters.jl as DimensionalData.jl + geospatial stuff, and since the docs are separated, I could not really now what belonged to which library.

I would have appreciated to see some examples combining things specific to Rasters.jl with DimensionalData.jl (e.g. groupby, calls to metadata and other "basic" stuff). For lower level packages this is not really a problem, but for packages like this one which sit at the top of the stack, it is also nice to have a good understanding of all the functionalities they give you access too, without having to bother to understand the tree of dependencies and checking each documentation separately.

[rafaqz]

Yeah, we really need that kind of high level docs integration. The packages to do this well are pretty new, and docs are just a lot of work and we all work full time on things other than documentation. Just getting Rasters and DD to the current state has been a huge effort from @lazarusA, a few other and myself.

A key problem is writing Julia code is very efficient, so we end up maintaining dozens of packages. But writing docs takes the same time as in any other language and we just don't have time for doing it well relative to the functionality we can write.

I document function API docs as I write and modify code. But I only rarely have time to do the kind of high level overviews you are talking about despite how needed they are. Its basically a completely separate process to development that very few people besides @lazarusA put real time into.

[JordiBolibar]

Yes, I completely understand. Docs take a huge time.

Nonetheless, perhaps you have some simple examples lying around that could simply be added to some of the sections that @lazarusA mentioned. I'm just trying to find an easy solution for new users 😄

[tiemvanderdeure]

Maybe we could add a "Dimensional operations" section under Manual, where we just explain how Rasters and DimensionalData are related, and link to (relevant sections of) the DD docs. If we're a bit clever then users searching for 'group by' might just end up at that page and from there on the relevant section of the DD docs.

I know it says in multiple places that Rasters extends DimensionalData, but I don't think the docs anywhere recommend to go to the DimensionalData docs if you're looking for something you can't find in the Rasters docs.

[asinghvi17]

We should add that to the homepage as a prominent hero card as well!