Documentation restructure

[reint-fischer]

As we move to v4, this might be a good opportunity to rethink what our documentation does and how it works for 1. new users and 2. experienced users. Based on some guidelines from PyOpenSci and Divio, I have started a conceptual draft for what the new structure of the documentation could look like:

Proposed structure:

• Getting Started
  o Installation
  o Quickstart Tutorial (completely rewrite)
  o Parcels concepts (explanation); include Interpolators
  o Analyse Output Tutorial (https://github.com/Parcels-code/10year-anniversary-session5/blob/main/animations_tutorial.ipynb and https://lagrangian-diags.readthedocs.io/en/latest/tutorials/analysis-cookbook.html)
• How to / User Guide
  o Set up FieldSets
  o Create ParticleSets
  o Write Kernels
  o Write Interpolators
  o Test for numerical accuracy/sensitivity (Add a tutorial to help users choose an appropriate advection kernel #1549)
  o Run an efficient simulation
  o Migrate from v3 to v4
  o Other How to’s
• Contributing
  o Developers guide
  o Versioning policy
  o Dev-notes
• Community
  o GitHub
  o Zulip
  o Example scripts and kernels
• Reference API

What I aimed to achieve here is to have a more clear separation between new users (Getting Started) and experienced users (How to Guides). It also gives our contributing guidelines a more central space. Please feel free to point out any section or pages that should be added.

Another question is whether these should all be tutorials as jupyter notebooks with their output included, if we leave out the outputs (currently the case for v4 if I am not mistaken), or if some should be only Markdown.

[VeckoTheGecko]

Woah, love this! 🤩

Some thoughts...

Should we add a page in the User Guide on working with various hydrodynamic input? (we can also go over the topic of grids here?) Or would that be best discussed in "Parcels concepts" (where we can explain structured/unstructured grids and how we tackle them).

---

• Example scripts and kernels

What do you envision going here? Is this wrapping in some of the work from parcels_contributing?

---

I assume versioning policy and dev-notes can go under contributing?

---

Is there a way that we can have a community page? This would be good to house links to the new Zulip, other interesting resources, and (e.g.,) a community calendar if we do office hours. Where would the link for this go? In the header?

---

• Analyse Output Tutorial (add parts of Vesna’s tutorial?)

I assume you mean this tutorial? https://lagrangian-diags.readthedocs.io/en/latest/tutorials/analysis-cookbook.html or is there another? I definitely think it would be good to include info from here - I think its really important.

---

• Parcels Cheat Sheet?

I think this would be useful for users, would be good to further discuss what you have in mind (especially if we can do this in a way with low maintenance burden).

---

What I aimed to achieve here is to have a more clear separation between new users (Getting Started) and experienced users (How to Guides). It also gives our contributing guidelines a more central space. Please feel free to point out any section or pages that should be added.

I think this is really good.

---

Another question is whether these should all be tutorials as jupyter notebooks with their output included, if we leave out the outputs (currently the case for v4 if I am not mistaken), or if some should be only Markdown.

For context, we're stripping output in v4 since the notebooks aren't finalised and it doesn't really make sense to commit results now.

I think it would be good to discuss this and list pros and cons wrt. maintenance, integration with (e.g.,) Binder, user experience (showing rendered outputs) - there are lots of options available (notebooks like before, or even having Markdown docs that can be run like they're notebooks). Not sure what the answer should be

[reint-fischer]

Thanks!

Should we add a page in the User Guide on working with various hydrodynamic input? (we can also go over the topic of grids here?) Or would that be best discussed in "Parcels concepts" (where we can explain structured/unstructured grids and how we tackle them).

Yes, I envision that this would go under “Set up FieldSets”. We now have a mix of tutorials for specific hydrodynamic fields (NEMO 3D, CROCO 3D) and more general FieldSet options such as working with Grid indexing and calendars. I think we can think a bit better about what the difference is between these two types of guides and how to reflect that under the “Set up FieldSets” tab, but I think they should go there.

• Example scripts and kernels

What do you envision going here? Is this wrapping in some of the work from parcels_contributing?

Yes, exactly, although maybe we don’t want it to be a full page, but just a link?

I assume versioning policy and dev-notes can go under contributing?

Yes, I’ve edited them in.

Is there a way that we can have a community page? This would be good to house links to the new Zulip, other interesting resources, and (e.g.,) a community calendar if we do office hours. Where would the link for this go? In the header?

Could the solution to this be to make the Contributing header into a Community header? That way we can host all of the above under this header. I am not sure I completely understand how far we want to blur the two or keep them separate. parcels_contributing is maybe a good example of a space which is now somewhere between the two: not really developing, but still contributing to the use of parcels by the community.

• Analyse Output Tutorial (add parts of Vesna’s tutorial?)

I assume you mean this tutorial? https://lagrangian-diags.readthedocs.io/en/latest/tutorials/analysis-cookbook.html or is there another? I definitely think it would be good to include info from here - I think its really important.

Thanks for this addition! I think @erikvansebille meant this tutorial from the conference: https://github.com/Parcels-code/10year-anniversary-session5/blob/main/animations_tutorial.ipynb

• Parcels Cheat Sheet?

I think this would be useful for users, would be good to further discuss what you have in mind (especially if we can do this in a way with low maintenance burden).

I like quick visual overviews of what the most common classes and their methods are. I am not sure yet how useful it would be for a package of our size, but I’d be happy to brainstorm about what could go in there. Here is a Pandas example.

I think it would be good to discuss this and list pros and cons wrt. maintenance, integration with (e.g.,) Binder, user experience (showing rendered outputs) - there are lots of options available (notebooks like before, or even having Markdown docs that can be run like they're notebooks). Not sure what the answer should be

I agree, maybe we should discuss this in a separate issue?

[VeckoTheGecko]

• Example scripts and kernels

What do you envision going here? Is this wrapping in some of the work from parcels_contributing?

Yes, exactly, although maybe we don’t want it to be a full page, but just a link?

A link is good

Could the solution to this be to make the Contributing header into a Community header? That way we can host all of the above under this header.

That's the current approach we're going for (in the header we call it "contributing" but the page it links to is the community page). I think splitting it out into a separate page would be nice for visibility, and we can rename the current page from community to development.

The concern that I have with housing contributing/development instructions under "community" is that it makes first time contributor instructions more hidden - it would be good to make them more visible for people new to the project.

• Parcels Cheat Sheet?

I think this would be useful for users, would be good to further discuss what you have in mind (especially if we can do this in a way with low maintenance burden).

I like quick visual overviews of what the most common classes and their methods are. I am not sure yet how useful it would be for a package of our size, but I’d be happy to brainstorm about what could go in there. Here is a Pandas example.

I see. If this can be done programmatically in a way by pulling in from our documentation that would be great. If this has to be done manually (which I think is done in the case of Pandas) by editting PDFs then I'm afraid it would turn into a significant maintenance burden that wouldn't be worth it.

I think it would be good to discuss this and list pros and cons wrt. maintenance, integration with (e.g.,) Binder, user experience (showing rendered outputs) - there are lots of options available (notebooks like before, or even having Markdown docs that can be run like they're notebooks). Not sure what the answer should be

I agree, maybe we should discuss this in a separate issue?

Agreed