search

ioos / Cloud-Sandbox

IOOS' Coastal Modeling Cloud Sandbox provides a framework for developing, modifying and running models in the cloud. It provides repeatable configurations, model code and required libraries, input data and analysis of model outputs. The Sandbox supports not only the development of services and models, but also Cloud HPC to run and validate models.
https://www-sandbox.ioos.us/
BSD 3-Clause "New" or "Revised" License
15 stars 12 forks source link

Update README with more detail #26

Open dpsnowden opened 3 years ago

dpsnowden commented 3 years ago

The top level README.md could use more detail. The document starts off with installation instructions but skips over the description of the overall project. Good examples of READMEs are https://gist.github.com/DomPizzie/7a5ff55ffa9081f2de27c315f5018afc and https://github.com/matiassingers/awesome-readme

There are several good suggestions of sections in those examples but perhaps the most important is the detailed Description section. I read the entire document and still don't know what the Cloud-Sandbox actually does. @patrick-tripp

dpsnowden commented 7 months ago

@Michael-Lalime, can we make this a higher priority? The readme currently needs to be rewritten. I want to come here and quickly understand the target audience, what the sandbox does currently (and what we hope it will do in the future), and why it makes life easier for the target audience. Cleanly separating the current capabilities from the future goals is important. Here's an excellent list of awesome-readme files that can guide you.

KatherinePowell-NOAA commented 6 months ago

Discussed with Michael, I will be adding to the ReadMe as part of the outreach tasks, and as I am updating the tutorial.

jonmjoyce commented 5 months ago

Hi @KatherinePowell-NOAA, do you want any assistance on the documentation updates? @patrick-tripp suggested this would be a good place for me to start.

KatherinePowell-NOAA commented 5 months ago

Great idea - sure! I need to update the Readme. We have a 'document-development' branch that we are using. I was going to go through the examples suggested: https://github.com/matiassingers/awesome-readme lists. There's A LOT! Do you want to read through what is there and also check out that link?

jonmjoyce commented 5 months ago

Who are the target audience(s) that we should aim to inform with the README? Are most people configuring a new sandbox, running a model, or just want to know what it does?

Just off the top of my head, a few things that can be addressed are a Table of Contents, more writeup with general conceptual info (probably Patrick's slides are a good start), and then leading the readers through the appropriate user stories. Then if applicable, look into relevant badges, linters, etc.

jonmjoyce commented 4 months ago

Do we want to add rendered GitHub pages documentation in addition to the README?

I also just saw https://www-sandbox.ioos.us/overview for the first time. Where does that content get managed? Is it up-to-date?

Michael-Lalime commented 4 months ago

Jonathan,

I'll let Micah Wrengren weigh in on the rendered GitHub pages, but as to the overview page I believe that is several years old so would need some review to determine if it's up to date so I would use at your own risk for the time being.

Michael

On Fri, Jun 7, 2024 at 4:45 PM Jonathan Joyce @.***> wrote:

Do we want to add rendered GitHub pages documentation in addition to the README?

I also just saw https://www-sandbox.ioos.us/overview for the first time. Where does that content get managed? Is it up-to-date?

— Reply to this email directly, view it on GitHub https://github.com/ioos/Cloud-Sandbox/issues/26#issuecomment-2155519285, or unsubscribe https://github.com/notifications/unsubscribe-auth/AR7UUIHWAYGMRSNCCKW4XU3ZGILWFAVCNFSM47WY5M32U5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TEMJVGU2TCOJSHA2Q . You are receiving this because you were assigned.Message ID: @.***>

patrick-tripp commented 4 months ago

Personally, I prefer having everything in README and other markdown files. But if you think adding rendered content will add value, go for it.

The sandbox-ioos.us website is out of date.

Michael-Lalime commented 4 months ago

Thanks Patrick!

On Fri, Jun 7, 2024 at 4:52 PM Patrick Tripp @.***> wrote:

Personally, I prefer having everything in README and other markdown files. But if you think adding rendered content will add value, go for it.

The sandbox-ioos.us website is out of date.

— Reply to this email directly, view it on GitHub https://github.com/ioos/Cloud-Sandbox/issues/26#issuecomment-2155527077, or unsubscribe https://github.com/notifications/unsubscribe-auth/AR7UUIGDGQ4I6BEGJRSC6VLZGIMQ3AVCNFSM47WY5M32U5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TEMJVGU2TENZQG43Q . You are receiving this because you were assigned.Message ID: @.***>

ocefpaf commented 4 months ago

BTW, we can use the readme as part of the rendered docs to keep them in sync. We do this in compliance-checker: https://github.com/ioos/compliance-checker/pull/1077

jonmjoyce commented 4 months ago

I pushed some initial README updates a few weeks ago but looks like the PR #94 has not been reviewed. I'm not sure what your review process is so I tagged @Michael-Lalime and @KatherinePowell-NOAA as I thought you'd want to review the updates.

Michael-Lalime commented 4 months ago

Hi Jonathan,

Thanks, I hadn't noticed that I was tagged; I guess we don't get emails when that happens. I'll take a look today.

Michael

On Tue, Jul 2, 2024 at 11:30 AM Jonathan Joyce @.***> wrote:

I pushed some initial README updates a few weeks ago but looks like the PR

94 https://github.com/ioos/Cloud-Sandbox/pull/94 has not been

reviewed. I'm not sure what your review process is so I tagged @Michael-Lalime https://github.com/Michael-Lalime and @KatherinePowell-NOAA https://github.com/KatherinePowell-NOAA as I thought you'd want to review the updates.

— Reply to this email directly, view it on GitHub https://github.com/ioos/Cloud-Sandbox/issues/26#issuecomment-2203535224, or unsubscribe https://github.com/notifications/unsubscribe-auth/AR7UUIEDVWQCZBSPQVUQPVTZKLBPLAVCNFSM47WY5M32U5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TEMRQGM2TGNJSGI2A . You are receiving this because you were mentioned.Message ID: @.***>

Michael-Lalime commented 4 months ago

Scratch that, I did get an email but it was on a busy day and I probably meant to get to it and then forgot. I'm sorry I missed it the first time around.

Michael

On Tue, Jul 2, 2024 at 11:34 AM Michael Lalime - NOAA Affiliate < @.***> wrote:

Hi Jonathan,

Thanks, I hadn't noticed that I was tagged; I guess we don't get emails when that happens. I'll take a look today.

Michael

On Tue, Jul 2, 2024 at 11:30 AM Jonathan Joyce @.***> wrote:

I pushed some initial README updates a few weeks ago but looks like the PR #94 https://github.com/ioos/Cloud-Sandbox/pull/94 has not been reviewed. I'm not sure what your review process is so I tagged @Michael-Lalime https://github.com/Michael-Lalime and @KatherinePowell-NOAA https://github.com/KatherinePowell-NOAA as I thought you'd want to review the updates.

— Reply to this email directly, view it on GitHub https://github.com/ioos/Cloud-Sandbox/issues/26#issuecomment-2203535224, or unsubscribe https://github.com/notifications/unsubscribe-auth/AR7UUIEDVWQCZBSPQVUQPVTZKLBPLAVCNFSM47WY5M32U5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TEMRQGM2TGNJSGI2A . You are receiving this because you were mentioned.Message ID: @.***>

Michael-Lalime commented 4 months ago

I think the readme updates looked good to me. I only had a couple comments. What do others think?