Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add explanatory test to make the documentation examples more understandable #95

Closed
paigem opened this issue Mar 6, 2024 · 0 comments · Fixed by #99
Closed

Add explanatory test to make the documentation examples more understandable #95

paigem opened this issue Mar 6, 2024 · 0 comments · Fixed by #99

Comments

@paigem
Copy link
Contributor

paigem commented Mar 6, 2024

Feature request: Add more helpful motivating and descriptive language to the 3 documentation examples

The examples in the documentation could use some more descriptive language to describe what is being demonstrated. I put in a PR to help get started with this, but the examples have very few descriptions of what is going on and, importantly, why it's a useful example. A couple sentences at the top of each of the 3 examples (along the lines I suggest in my PR when describing the examples) would be very helpful for users to successfully follow along with those examples.

For example, in the first example open_process_files:

  • The example starts by saying "Start by importing the functions." I suggest a sentence or two before this should be added to let the user know exactly what this example will demonstrate.
  • The term "process" here is not clear to me. Processing data can take many forms. If possible, either at the top of the example or later when discussing the steps to "process" files, please explain what type of processing occurs and why this is useful for the user.
  • The first section title in this example is "First open the domain_cfg and nemo files into 2 datasets". Could you better explain what a domain_cfg file is and why we need to open that and the "Nemo files" as 2 datasets?

These are just a few examples - in general, a bit more explanatory text would be helpful at each main step of each example.

Apologies that I can't easily put in a PR for this, since I don't know enough about NEMO to do this well. Hopefully this will be relatively straight-forward for a NEMO and xnemogcm expert like you @rcaneill! 😊

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant