MetOffice / MetOffice/LFRic-Atmosphere-Training

Landing pages: move additional links to a further reading section at the end of each page

Open
#355 1 comment 1 reaction 0 assignees View on GitHub
Content
Dominant language
Jupyter Notebook
Stars
11
Forks
6
Avg merge
5d 19h
Merged PRs (30d)
9

Description

The [course landing page][home], and some module and content pages, link to a
number of external resources before learners have worked through any of the
core material. This came up in a review of the material from a pedagogical
perspective.

The suggestion is to review whether these links would work better at the end
of each page, in a clearly labelled further reading section. That way,
learners are guided through the core material before being directed
elsewhere. Essential navigation should stay easy to find, including:

- choosing a platform;
- getting help through GitHub Discussions (added in #350);
- the course contents.

This relates to the point about cognitive overload in #134, which mentions
external links as one of the contributing factors.

## Observations

### Home page

([source](https://github.com/MetOffice/LFRic-Atmosphere-Training/blob/942d960/source/index.rst#L9-L35))

The first three paragraphs contain five external links, three of which go to
the Momentum website.

The prior knowledge note says "Before diving into this course, it's helpful to
have some foundational knowledge in the following areas", followed by links to
four external tutorials. This could be read as advice to stop and complete
those tutorials first. It also sits uneasily with the sentence just before it,
which says the course will point learners to refresher material where it is
needed.

### Module 1 landing page

([source](https://github.com/MetOffice/LFRic-Atmosphere-Training/blob/942d960/source/introduction/index.rst#L22-L25))

A link to the LFRic scalability paper appears before the aims and objectives.

### Content pages

The unstructured introduction has a list of 11 tools, with around 20 links,
partway down the page
([source](https://github.com/MetOffice/LFRic-Atmosphere-Training/blob/942d960/source/mesh_overview/unstructured/unstructured_introduction/unstructured_introduction.rst#L254-L280)).

The Land Surface and Ocean pages already end with a "Further resources"
section, which is a good model to follow. However, the heading varies between
pages: "Further resources", "See also" and `seealso` boxes are all used.

## Suggested approach

- End each page with a section that has the same heading on every page (for
example "Further reading"), and put additional links there.
- Keep a link inline only when learners need it to complete a step, such as
requesting access or downloading data.
- Where a link is mainly there to explain a term, use the existing
[glossary](https://github.com/MetOffice/LFRic-Atmosphere-Training/blob/942d960/source/glossary.rst)
with `:term:` instead.
- Reorder the home page as follows:
1. what the course is, with at most one link to the Momentum website;
2. who it is for;
3. choosing your platform;
4. contents;
5. getting help;
6. further reading.
- Apply the same approach to the module landing pages.

A possible rewording of the prior knowledge note:

> This course is designed for new users of LFRic Atmosphere who have a general
> background in weather or climate science. You should be comfortable working
> in a Linux terminal and have some experience of Python.
>
> The course also uses Cylc, Rose, version control (FCM and Git) and Jupyter
> notebooks. You do not need to know these in advance. Where a section relies
> on one of them, we explain what you need and suggest where to find out more.
> Links to introductory material are listed under further reading at the end
> of this page.

## Questions for the Met Office team

1. Is the list of prior knowledge meant as a requirement, or as background
that is helpful but not essential? The wording should make this clear.
2. Are there links that need to stay near the top of the page, for example
for Momentum Partnership or communications reasons?
3. Would a further reading section on each page work well, or would a single
central page of resources be preferable?

[home]: https://metoffice.github.io/LFRic-Atmosphere-Training/

Contributor guide

No contributing guide indexed for this repository

Research direction

Review source/index.rst, source/introduction/index.rst, and source/mesh_overview/unstructured/unstructured_introduction/unstructured_introduction.rst, using the existing Land Surface and Ocean "Further resources" sections as a model. Move non-essential external links into consistently titled further-reading sections, keep required navigation and step-specific links inline, and use source/glossary.rst for term links where appropriate. Done means the affected pages guide learners through core material before additional resources and retain essential navigation.

Written by the indexing model from the issue text.

Assessment

Tech stack
jupyter-notebook
Domain
content, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.