Devise naming structure for scripts in this repo

[navidcy]

I think, contrary to what @AndyHoggANU was implying/suggesting during the MOM meeting on Apr 2nd, that the repository will benefit a lot if the ContributedExamples directory is cleared out!

Having code/notebooks that don't work or with no comments explaining to user to the bare minimum what the code is trying to achieve is, in my opinion, a bad practice. To be honest, a major reason I was pulling back initially from using the cookbook was, probably, this chaos and that notebooks I was trying to run were failing leaving me hopeless...

10 examples that work and nicely explain what is going on are much better than 100 examples that mostly/partly work sometimes but only their authors know what they are trying to compute (and that given not much time has passed so that even the authors have forgotten everything).

That said, I propose a much more major restructure from what the issue subject suggests. Disclaimer: It may sound a bit more drastic than simply "a naming structure".

I suggest we drop the concept of ContributedExamples. We should rename the ContributedExamples to sandbox to denote a place with things that perhaps don't work/are deprecated/outdated etc. As part of the Hackathon and as a vision for the Cosima-recipes we should aim to move the notebooks from sandbox to DocumentedExamples.

In short: let's make all examples documented ones. I think that something along those lines would improve the repository and, consequently, benefit the COSIMA community and beyond...

Opinions? @AndyHoggANU, @aekiss, @rmholmes, @aidanheerdegen, @angus-g, @kialstewart, others?

[rmholmes]

I agree that ContributedExamples should not contain a mishmash of everything that anyone wants to add, whether it works or not. Replacing with sandbox is a good idea.

However, one issue with getting rid of ContributedExamples altogether is that the bar to turn an example into a DocumentedExamples might be a bit high for most people (i.e. it requires more time than people might have to go through and explain exactly what they are doing all the way through). Can we retain ContributedExamples as a middle-ground somehow? I.e. -> examples that work, but are not neccessarily well documented. If they then break in the future, they can be moved back into sandbox.

[navidcy]

the bar to turn an example into a DocumentedExamples might be a bit high for most people (i.e. it requires more time than people might have to go through and explain exactly what they are doing all the way through)

But @rmholmes, uncommented code is useless... similarly to uncommented jupyter-notebook cells. This is a public repository, not each persons notes. The bar should be a bit higher, indeed. That would be better for everybody (mostly for newbies) in the long run. I insist, that messy contributed examples create confusion...

I'm not implying that each person should do this by themselves. What I suggest, is that when somebody pushes a PR with a .ipynb example they did, then the repo admins should give feedback or modify the PR to make the .ipynb at the level of DocumentedExamples.

[rmholmes]

Perhaps. I was thinking that there was a difference between commented code (which I totally agree is essential) and a documented example (which is much more extensive in terms of explaining how and why things are done the way they are). But I'm happy to be corrected.

[navidcy]

A notebook that consists of a series of cc.load... and plt.plot(x, y, z) commands is, in my view, uncommented code. Perhaps phrased better "illustrated uncommented code" :)

[navidcy]

hm... perhaps we are getting into semantics here (and that's diverting our focus).

I'll try go through the contributed examples and point out which ones might make no sense and need either deletion or some comments

[AndyHoggANU]

How about this - during the hackathon, people can develop and improve contributed examples. Any documentation they put there is to be encouraged. When they do their pull request, then the administrator can choose to either upgrade it to a documented example (adding additional documentation if needed) or leave it there.

Deleting ContributedExamples is an aspirational goal. Let's install the sandbox and see how ContributedExamples evolves ...

[AndyHoggANU]

BTW, I have added a Sandbox directory

[navidcy]

in #53? doesn't seem that you did.. I'll do it.

[angus-g]

Note that git requires some kind of a file inside a directory, or it'll be ignored. Could be as simple as an empty .gitignore or a directory-specific README

[AndyHoggANU]

Yeah, that was probably where I went wrong ...

[navidcy]

I added a README.md

[adele-morrison]

Should we close this? We're now discussing naming structure in the MOM6 issue instead.