Collate documentation

[julia-neme]

The amazing-super-fun hackathon made me want to review pull requests, and since I didn't go to the review tutorial because I had some even more basic git/github pitfalls, I missed out on learning that day. So I searched for documentation/step-by-step tutorials on how to do it because I wanted to run the notebooks to test them which is not as trivial as opening reviewNB and commenting. I have not found that documentation, but did receive help from people via chat. There are two possibilities:

1. My searching skills are flawed (probably true) and said documentation exists somewhere.
2. Documentation does not exist.

I think in either case, it would be cool to populate the repo Wiki so that others that struggle like me have 1 place and only 1 place where to go to follow steps that enable them to contribute to the recipes. Hopefully this boosts participation outside of the hackathons.

Thoughts?

I am happy to do this if people agree, and if someone wants to suffer with me please join :)

[adele-morrison]

Did you find this documentation that @navidcy recently made? https://cosima-recipes.readthedocs.io/en/latest/contributing.html#reviewing-existing-pull-requests

I think it would be great to expand this step:

• Clone the repository or the fork that the pull request was made from;

to be easier by suggesting people do the 'Checkout with GitHub CLI' instead, and adding some instructions on how to do that.

Also, maybe we could make a link to the above contribution docs on this 'Beginners Guide to the COSIMA Cookbook' page? I find it confusing that we have these 2 sets of different documentation pages.

Also, I find it quite confusing that the 'Beginners Guide to the COSIMA Cookbook' is at cosima-cookbook/wiki, not the cosima-recipes/wiki, because the most useful thing there is instructions on how to get the recipes working. Maybe that will get fixed if we go through with renaming this repository?

[navidcy]

Let’s bring the wiki in this repo!

[navidcy]

Thanks @julia-neme for opening this! Already it paved the way for @adele-morrison to express her confusion. I'm happy to hear more points of confusion from everyone so we resolve them!

[navidcy]

Sidenote: It's not related with this issue but I think renaming the repo will create huge issues... For example, consider all the posts in the forum linking to issues in this repo being broken.... I'll open another issue to discuss this and will put my reservations there.

[adele-morrison]

I'm not sure I feel super strongly either way on the renaming the repo topic, but just to note (from here):

When you rename a repository, all existing information, with the exception of project site URLs, is automatically redirected to the new name, including:

• Issues
• Wikis
• Stars
• Followers

[navidcy]

It’s unrelated to this issue

I'm not sure I feel super strongly either way on the renaming the repo topic, but just to note (from here):

When you rename a repository, all existing information, with the exception of project site URLs, is automatically redirected to the new name, including:

• Issues
• Wikis
• Stars
• Followers

Yes. But we are proposing to rename it to a name that already is a different repository!

[navidcy]

Btw, the Beginners Guide to the COSIMA Cookbook will become deprecated with the ACCESS Intake. So let's not put too much effort in it....?

[navidcy]

I stumbled upon this excellent blogpost on reviewing code. Should we add a url somewhere?

https://www.alexandra-hill.com/2018/06/25/the-art-of-giving-and-receiving-code-reviews/

[navidcy]

Here’s a youtube video of the blog above!

https://youtu.be/XY6eA2_2hOg?si=CDyUJ-FOqwo0JzxL

[lidefi87]

Do you think making short videos will make things clearer? I am thinking maybe making 2-3 minute videos showing how to do the basics will make following instructions easier.

Also, is there a way to pin these resources in the ACCESS-NRI forum? I am thinking just a post with useful links, nothing too complicated, but that would hopefully point people in the right direction.

[lidefi87]

Also, I think it is a good idea to include the resources you shared @navidcy

[julia-neme]

I have done a first draft of a wiki, where you can find (or I hope you can) all the steps to start contributing and reviewing using gadi/git/github. I've linked to github tutorials in some places, and wrote the steps I have used in others.

This is probably riddled with mistakes/not-best-practices. I would really appreciate people that are github savvy and total newbies to try some/all steps and edit where you see fit.

I think we should choose between having a wiki or a readthedocs.io, not have both. Having just one is cleaner and avoids redundancy. I am partial to the wiki because I find it more intuitive to find, but the wiki is also really easy to copy into the readthedocs.io if that's what people want! I would add a page with tips for good recipes/best practices with the stuff that's in readthedocs.io and what @navidcy talked about in the hackathon.

[navidcy]

Let's add a link to the repo's wiki in the README and in the readthedocs.io?

[adele-morrison]

I vote for the wiki and delete/shift over the readthedocs.io page. That way everything is at the same github repo link.

[navidcy]

So you suggest we move the wiki stuff in the readthedocs.io page?

[adele-morrison]

No, I suggest moving the info from readthedocs.io to the github wiki page. Then delete the readthedocs. Though maybe there is some good reason to have it there that I don't know about?

[navidcy]

Gotcha. I think everything (related instructions, cloning, contributions, PR reviewing etc) in the wiki would work!

[navidcy]

Btw I opened https://github.com/COSIMA/cosima-cookbook/issues/343 which is related.

[anton-seaice]

I don't have a view either way but one difference between a wiki and readthedocs is how they are authored.

A wiki can typically be edited, without review, by anyone with write access to the repository. For new and occasional contributors this may prevent them being able to make changes. (Although the access permissions can be changed, you can allow edits from anyone)

Readthedocs is within the repository, so changes are made by pull request and therefore require review also. Anyone can submit a pull request (and they don't need write access).

[navidcy]

I do prefer the readdocs place for things to be (for the reasons @anton-seaice mentioned!).

But, more importantly, I think it's good to have everything in one place! And that we actually have the information written down!

People are generally very reluctant in opening PRs and contributing, so when someone said "I'll make a wiki.." I was so excited that I didn't wanna add extra layers of complications.

So I suggest we gather everything in the cosima-recipe's wiki now, since after @julia-neme's attempt it's mostly there. Afterwards it would be very easy to move everything in the readdocs if we wanted to.

[lidefi87]

The wiki looks great @julia-neme 😀

[julia-neme]

It seems easy to transfer from one place to another! Why don't we keep editing in the wiki until more or less satisfied and then we decided? In my mind there seem to be two other things to include:

• Relevant info from the cosima-cookbook wiki
• Good practices on reviewing/documenting/etc by @navidcy

[navidcy]

@julia-neme is there anything else from the COSIMA-Cookbook Wiki that needs to come over or should we go ahead and delete that one and replace it with a link to this repo's wiki?

[julia-neme]

I think the wiki is done except for a new FAQ page. I don't think there is anything missing from the cookbook wiki. Please look at the FAQs and edit away. Or just delete the page if its not useful.

What should we do now?

• Option 1: put the wiki into readthedocs.io
• Option 2: do a couple of new pages in the wiki with tips on contributing etc.

[julia-neme]

What do people think? Move wiki to readthedocs or move readthedocs to the wiki? @navidcy @adele-morrison @edoddridge @lidefi87 and others?

[adele-morrison]

I prefer the wiki, because then everything is at the same weblink, and it's easy to navigate back to the code. But I can see the benefit of requiring review on readthedocs if others prefer that.

[navidcy]

What do you mean "everything is at the same weblink"?

[adele-morrison]

Wiki is at https://github.com/COSIMA/cosima-recipes/wiki, which has a 'Code' link in the top bar to take you back directly to the recipes.

Readthedocs is at https://cosima-recipes.readthedocs.io/en/latest/. I always find it tricky to navigate from there back to https://github.com/COSIMA/cosima-recipes.

[navidcy]

we can always fix that! the trick is to voice that you'd like that (as you did now!) :)

[edoddridge]

Perhaps unhelpfully, I would prefer it be part of read the docs. That way, all the user facing information is on the same site. It's a fair point though @adele-morrison. Would including a link back to GH on the main page be sufficient?

[navidcy]

It should be easy to include a link back to the GitHub repo. We should do that regardless what we decide on where to put the info.

@angus-g could we have a link to the main repo that is always visible (regardless what page of the readthedocs you are) in the readthedocs?

[julia-neme]

Perhaps unhelpfully, I would prefer it be part of read the docs. That way, all the user facing information is on the same site. It's a fair point though @adele-morrison. Would including a link back to GH on the main page be sufficient?

I think the idea here is to move everything to the wiki, or everything to readthedocs. Everything would be on the same site, but the question is which one hehe.

I think I'm with Adele in that readthedocs takes you to a website separate from the repository, and the wiki makes everything be in the same place. which I personally find tidier and easier to navigate.

But then, if we really want changes to the documentation to be reviewed, it must be in the readthedocs. I don't think many people want to/are actively editing the documentation, so not sure how much of an issue that is - but perhaps for the sakes of control as cosima grows it will be needed.

[navidcy]

Yes, I think forward thinking would urge us to move things in the readthedocs.

I agree w @edoddridge on this.

And @adele-morrison and @julia-neme's reservations regarding navigating back and forth can be alleviated. It's just a click away... We can add the link if it helps people of course now that we know!

[angus-g]

@angus-g could we have a link to the main repo that is always visible (regardless what page of the readthedocs you are) in the readthedocs?

Addressed in #439

[lidefi87]

Sorry everyone. I was away sick. This is looking really great and I agree that it may be best to keep everything in a single site, and the website seems to be the best place since we have some control over who edits it. But I do agree with Adele and Julia when they say that this may not be the most intuitive place as people are likely going to look for this information in GitHub.

[navidcy]

But I do agree with Adele and Julia when they say that this may not be the most intuitive place as people are likely going to look for this information in GitHub.

readthedocs is "in GitHub" for my books... it's just a nicer interface

how about now that we added the link to the repo?

[lidefi87]

I like it 😊 I think it should be easy to find. I quite like the guide, it was a great effort

[navidcy]

I suggest:

• a PR that modifies the README to point to the wiki where needed
• then close this issue since the Documentation is collated now all in one spot (mostly)!
• then a new PR that moves all the info within the readthedocs + some restructuring of sections (where needed)

What do you feel about this plan moving forward?

[julia-neme]

OK to me :) I can't get to it this week, but will next one!

[hrsdawson]

Sorry everyone. I was away sick. This is looking really great and I agree that it may be best to keep everything in a single site, and the website seems to be the best place since we have some control over who edits it. But I do agree with Adele and Julia when they say that this may not be the most intuitive place as people are likely going to look for this information in GitHub.

I don't know if it's too late to comment on this, but I'm going to confess that I wasn't really aware there was a readthedocs (🤦‍♀️). I've only ever gone to the wiki before. Now that I'm aware of it, I can easily navigate to it, but perhaps making the link more explicit/noticeable (if that's where the info is going) would be useful for others like me.

[navidcy]

We'll make sure the existence of it is available!

How were you navigating through the recipes if not via the readthedocs? Do you open the .ipynb files via GitHub's viewer? You are missing this nice view!

[hrsdawson]

How were you navigating through the recipes if not via the readthedocs? Do you open the .ipynb files via GitHub's viewer? You are missing this nice view!

Yep, that's exactly how haha.

[navidcy]

It's a bright day today then!

[julia-neme]

Weeeeeeeell I have to say that editing the readthedocs.io is not trivial at all. It will take me ages to understand sphynx and do a good job. I've tried a little test in my own fork in a new branch, but I will have to merge everytime I do a change to actually see what that changes does. Considering I will need a million iterations to get sphynx do what I want it to do, I don't think this is a sensible workflow and it will take me a so much time that I probably shouldn't be spending on this haha.

Summary, I don't think I have the time to translate the wiki to the readthedocs. If there are no volunteers to do this, I suggest we use the wiki instead. Changes are tracked anyways, only collaborators can edit plus no one really seems keen to go and fiddle with documentation/instructions.

[julia-neme]

PS I'd like to ignore my pull requests of the docs because it was a test only. Not sure why it got pulled automatically, and I don't know how to ignore it either.