Instance management docs

[j08lue]

I see we merged this PR that introduced a third section in the docs, called "Managing your Own VEDA":

• Add instance management section #182

I guess your goal with this new section, @aboydnw, is to have docs for platform content management that are universal to all instances, correct?

Right now those docs are still quite specific to the VEDA EarthData instance and our VEDA project team:

1. Adding Content lists the VEDA EarthData endpoints and repos and refers to the conventions we established.
2. All Usage Examples refer to datasets in VEDA EarthData catalogs and the thematic context of the EarthData instance.

I would in principle expect platform instance teams to create their own docs (internal or public), listing their content conventions and review processes, and for technical details referencing software usage and API docs that live with the software.

Do we really need this new section? If we do, do we need to adjust our content to better fit this model?

[aboydnw]

I would in principle expect platform instance teams to create their own docs (internal or public), listing their content conventions and review processes, and for technical details referencing software usage and API docs that live with the software.

This only seems reasonable for a) large projects like GHG or b) projects/programs totally unrelated to NASA & VEDA. Both of which I would say seem to be outliers in the near future. And in any case, we probably need some overarching VEDA documentation on "so, you want an instance, eh?" that lives outside of any single repo.

The idea behind the section is that somebody coming to docs has a few different questions they might be trying to answer:

1. What is this VEDA thing? (NASA VEDA Platform)
2. How do I use it? (Managing your Own VEDA)
3. What if something is missing or I want to contribute to it? (VEDA Open Source Ecosystem)

Each of those would represent scaling up in terms of level of involvement / technical expertise. Somebody trying to understand it probably already knows what it is and why it is valuable, but maybe is not interested in creating a PR to add functionality to the core code, for example.

So, in my opinion, we do need the section, and also need to adjust the content. I started doing that a little bit with some dashboard content, like referencing Earthdata instance things as examples, but we need more changes for sure. I don't know if it means we have to go back to the drawing board on the content and examples, we might just have to position them as examples or something like that.

[wildintellect]

+1 we need the section but can you clarify @aboydnw is it generic, or is it specific to an instance? if the latter, can we make it more clear in the title?

Do we expect other VEDA instance to fork this repo?

[aboydnw]

It's meant to be generic. The existing content probably needs to be massaged a bit, because it was originally just for the Earthdata instance so all the examples are from that instance.

I don't expect other VEDA instances to fork these docs and have their own, I see it is generic to VEDA as a product.

[wildintellect]

@aboydnw If it's generic where do the instance specific docs go? I'll be honest in Science Support we almost always need the instance specific docs. The generic docs are going to be almost static and rarely changing.

[aboydnw]

Ah okay. Maybe the projects with bigger budgets will fork these, like GHG Center? Otherwise every instance will have a repo and maybe anything instance-specific would go there.

I don't know that some of the smaller instances like earth.gov or Air Quality have given a ton of thought to that question. I think GHG has their own docs already, though.

[wildintellect]

Right https://us-ghg-center.github.io/ghgc-docs/
So where does https://hub.openveda.cloud get documented?

[j08lue]

What is this VEDA thing? (NASA VEDA Platform)
How do I use it? (Managing your Own VEDA)
What if something is missing or I want to contribute to it? (VEDA Open Source Ecosystem)

Ah, ok, then we had different ideas about the sections, @aboydnw. That explains why our mashup is confusing.

Let's use your distinction.

I would only have NASA VEDA instance specific hub and content docs, though. Yes, some of these instructions may be generic enough to apply to other instances. But then let them copy or refer to them. Rule of 3.