Feedback on technical guide

[sunnydean]

User Documentation for Platform Guide

• - It says, "Guidance on how to integrate external cloud computing services and other relevant platforms to EarthCODE". This implies it is guidance on how to integrate any platform into EarthCODE. I think this is perhaps more Guidance for Scientists on how to use an EarthCODE affiliated platform?
• Do scientists care more about "FAIR Open Science Development Capabilities" or "Infrastructure Capabilities"? I assumed they would be interested in what they could develop and this would come first?
• - Is "Data Access" part of FAIR Open Science Development Capabilities => Find, Access, etc. See above point - do we want to describe what they can do first and then the infrastructure it runs on next (unless they only care about high-performance hardware etc)?
• "Provide a list of curated tutorials for anyone interested in learning about your platform." Is this a list with links?
• "Full Documentation Can be Found At" - what is the difference between this and the above in Tutorials.

I also had a quick look at the other links and noted the following:

• About EarthCODE There is a lot of text. This looks well structured, but maybe one or two high level diagrams might help explain the concept. Something to look at and think yeah I like that, I will read on……

• - Maybe some process diagrams at a high level. I think this might clarify the overall choices at a glance.

• "10 minutes to EarthCODE"

• "Accessing EarthCODE" and "To get started, sign in using your GitHub account.". To get started you could just look at the Catalog or read about sections, there is no need to a use GitHub ID. Maybe put the following paragraph that comes after this first, which does state this.

• - The first diagram says, "workflow development". Is this commonly understood more than "experiment development"? Just a terminology question really based on what users think is normal.

• - Does development happen first and then publishing and then access and then visualisation? This order was different.

• - Maybe SSO is an enabler to do useful things and could be listed last.

[sunnydean]

• - It says, "Guidance on how to integrate external cloud computing services and other relevant platforms to EarthCODE". This implies it is guidance on how to integrate any platform into EarthCODE. I think this is perhaps more Guidance for Scientists on how to use an EarthCODE affiliated platform?

corrected

• Do scientists care more about "FAIR Open Science Development Capabilities" or "Infrastructure Capabilities"? I assumed they would be interested in what they could develop and this would come first?

the new summary section replaces this, see: https://esa-earthcode.github.io/documentation/Technical%20Documentation/Platforms/

and

https://esa-earthcode.github.io/documentation/Integrating%20New%20Platforms%20to%20EarthCODE/User%20Documentation%20for%20Platforms%20Guide#platform-summary

• - Is "Data Access" part of FAIR Open Science Development Capabilities => Find, Access, etc. See above point - do we want to describe what they can do first and then the infrastructure it runs on next (unless they only care about high-performance hardware etc)?

I think this is clearer now in the features summary part and the workflow dev environment sections

• "Provide a list of curated tutorials for anyone interested in learning about your platform." Is this a list with links?

yes, made it clearer.

• "Full Documentation Can be Found At" - what is the difference between this and the above in Tutorials.

I think this should be the official documentation pages, the other one above is videos, guides, workshops, tutorials, examples, sessions, etc.. etc..

made it clearer

---

I also had a quick look at the other links and noted the following:

• About EarthCODE There is a lot of text. This looks well structured, but maybe one or two high level diagrams might help explain the concept. Something to look at and think yeah I like that, I will read on…… Maybe some process diagrams at a high level. I think this might clarify the overall choices at a glance.

related to this one, #86

was asked to simplify it quite a bit to keep it streamlined for users

---

"10 minutes to EarthCODE"

• "Accessing EarthCODE" and "To get started, sign in using your GitHub account.". To get started you could just look at the Catalog or read about sections, there is no need to a use GitHub ID. Maybe put the following paragraph that comes after this first, which does state this.

good idea, switched the order

• - The first diagram says, "workflow development". Is this commonly understood more than "experiment development"? Just a terminology question really based on what users think is normal.

I think workflow is more synonymous to code dev environment, which is what I'm trying to say here, but point taken to avoid confusion

• - Does development happen first and then publishing and then access and then visualisation? This order was different.

I think one section gives at examples of what platform tools provide, while the other one then goes into -- generally in EarthCODE.

i.e. first people choose a platform that does these things (visualization, access, workflow dev, etc..) then they publish

• - Maybe SSO is an enabler to do useful things and could be listed last.

I think that's covered in the first section, but added a bit more details there

[sunnydean]

@GarinSmith applied the changes based on these - apologies for the delay - most of these were part of other tickets' comments as well