equinor / equinor/ert

Enhance ERT docs main page

Open
#4,407 0 comments 0 reactions 0 assignees View on GitHub
documentation enhancement
Dominant language
Python
Stars
161
Forks
141
Avg merge
2d 4h
Merged PRs (30d)
138

Description

I'm working my way into the docs and propose some changes to the [ERT docs main 'Welcome' page](https://ert.readthedocs.io/en/latest/index.html):

- Continue to lead with the high-level "what is this thing?".
- A visually descriptive picture (short and wide) would be nice.
- Add some conspicuous 'big picture' links for people in a hurry, in particular:
- Getting Started
- User Guide (currently called 'Reference' but that makes me think of the API docs)
- API reference / developer docs
- Some practical / context links:
- Mention that it's part of FMU
- Link back to the GitHub repo
- Make sure the arrow buttons lead to the next content (currently the _Next_ button leads to a blank page).
- Add "(open access)" to the copyright notice in the footer to make sure people can see the open license applies to the docs too; `sklearn` does this and I think it's good.

It's common to have a table of contents here, but I'm not sure it adds anything, given that it's basically there in the sidebar.

Eventually we could prettify this page a bit using something like [`sphinx-design`](https://sphinx-design.readthedocs.io/en/latest/) to make some cards (if and when it's warranted by the depth of content).

For reference, my go-to projects for awesome docs are Leo Uieda's [Fatiando project pages](https://www.fatiando.org/). Also [the NumFocus family of projects](https://numfocus.org/sponsored-projects) of course.

Contributor guide

Open the contributing guide

Research direction

Start with the linked ERT docs Welcome page and inspect the surrounding documentation navigation and footer configuration. Done means the page has the requested overview, image, links, FMU and repository context, corrected Next navigation, and the open-access copyright wording.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.