Update README with more detail #26
Comments
|
@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. |
|
Discussed with Michael, I will be adding to the ReadMe as part of the outreach tasks, and as I am updating the tutorial. |
|
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. |
|
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? |
|
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. |
|
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? |
|
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
<#26 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AR7UUIHWAYGMRSNCCKW4XU3ZGILWFAVCNFSM47WY5M32U5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TEMJVGU2TCOJSHA2Q>
.
You are receiving this because you were assigned.Message ID:
***@***.***>
|
|
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. |
|
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
<#26 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AR7UUIGDGQ4I6BEGJRSC6VLZGIMQ3AVCNFSM47WY5M32U5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TEMJVGU2TENZQG43Q>
.
You are receiving this because you were assigned.Message ID:
***@***.***>
|
|
BTW, we can use the readme as part of the rendered docs to keep them in sync. We do this in compliance-checker: ioos/compliance-checker#1077 |
|
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. |
|
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 <#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
<#26 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AR7UUIEDVWQCZBSPQVUQPVTZKLBPLAVCNFSM47WY5M32U5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TEMRQGM2TGNJSGI2A>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
|
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 <#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
> <#26 (comment)>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AR7UUIEDVWQCZBSPQVUQPVTZKLBPLAVCNFSM47WY5M32U5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TEMRQGM2TGNJSGI2A>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>
|
|
I think the readme updates looked good to me. I only had a couple comments. What do others think? |
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
The text was updated successfully, but these errors were encountered: