Improve the usability of the documentation

[stichbury]

Context

It's been a few years since we released the Kedro documentation and we have yet to make any major updates to the look and feel beyond some basic skinning for brand changes and changes to the order of pages. We did some user research recently and, while there are other high priorities that were reported, such as search and content updates, we did receive some feedback about the design of the docs. I'll share that separately to maintain the privacy of the interviewees.

I think it's also clear that our docs don't compete with other similar projects in presentation style, and they don't stack up well against our brilliant website and blog design. We receive several thousand visits to our docs landing page in any 30 day period so this matters. Having a competitive style and improved usability is key to ongoing success of the project.

Detailed description of some of the problems

As mentioned, I'll share quotes separately but it is clear from looking at the documentation home page that we could improve it.

Issues include: white space on the right hand side of the homepage but a wide span of text on all other pages except search, home page is just a list of links that mirrors the table of contents, limited in-page navigation.

There is a separate discussion to be had on the organisation of the content into more persona-led "journeys" since we don't segment the readership into different paths depending on their needs. However, I want this ticket to focus on finding great examples of documentation in the same arena as ours, and building a set of proposed designs. We can separately decide on content organisation if/as we agree on the most usable layout for Kedro users as the project moves forwards.

Requirements

I don't want to influence @stephkaiser in terms of design but I think these are great examples of documentation that we could emulate.

• DVC
• scikit-learn (For the homepage design. One of our survey participants specifically called out these docs as something we should aspire to become, but I feel the actual content pages have quite a few of the problems that we do)
• sktime was also suggested to us by one of our interviewees

---

Some themes we could consider:

• awesome sphinx

---

• Sphinx book

---

Also from kedro-org/kedro#2394 (from @astrojuanlu)

• [Furo](https://pradyunsg.me/furo/customisation/ (left + right navigation))

---

• [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/layout.html (left + right + top navigation))

---

• [Lutra](https://pradyunsg.me/lutra/porting/organise-configuration/ (left + right + top navigation))

Possible approaches

• One possible approach to this is to pick one of the sphinx themes above as the basis of our work and repurpose it.
• An alternative is to rebuild docs entirely into the website if we find a look and feel in docs that isn't Sphinx based and don't believe we can adequately reproduce it.

Next steps

I need to discuss further with @stephkaiser and the broader team to evaluate available time from Design and beyond.

[astrojuanlu]

Some notes on the scope of this ticket. Adapted from @stichbury original comment:

 Detailed description of some of the problems

[...]

1. white space on the right hand side of the homepage but a wide span of text on all other pages except search
2. home page is just a list of links that mirrors the table of contents
3. limited in-page navigation

Those are the important bits from the "graphical design" perspective. For (1), our current theme is famously not optimised for wide screens https://github.com/readthedocs/sphinx_rtd_theme/issues/295 and in general is poorly maintained, that's why we proposed exploring other Sphinx themes. (2) is about having a more attractive home page that is not only a list of links, there are several examples we could draw inspiration from (not to mention the "Welcome to X documentation!" that I consider a bit lame). (3) is about using the empty space from (1) to have an in-page table of contents, as some of the alternative Sphinx themes show.

Then on the docs structure:

There is a separate discussion to be had on the organisation of the content into more persona-led "journeys" since we don't segment the readership into different paths depending on their needs. However, I want this ticket to focus on finding great examples of documentation in the same arena as ours, and building a set of proposed designs. We can separately decide on content organisation if/as we agree on the most usable layout for Kedro users as the project moves forwards.

So let's start with the graphical elements and then continue with the information architecture reorgs that are needed.

Finally, it's important to note that the current baseline for this workstream should be the "meganav" that's already implemented but not visible:

https://docs.kedro.org/en/develop/ ⌛ https://docs.kedro.org/projects/kedro-viz/ https://docs.kedro.org/projects/kedro-datasets/en/latest/

Hence I add 1 more point: consistency across subprojects.

[datajoely]

Is it possible to do a "did you mean?" page on 404 which offers URLs suggestions? This is my biggest gripe doing user support as I search for page which no longer exists on a newer version.

[astrojuanlu]

That would be rad - adding that to https://github.com/kedro-org/kedro/issues/2951

[astrojuanlu]

Timely https://labs.quansight.org/blog/sympy-documentation

[stichbury]

Some data from @amandakys

• Nav bar: On average: just under one third of users interact with it per day,
• Search bar: On average: one third users interact with it per day, but less times per day than nav
• 10% of the time, the landing page was the home page.
• 7% of the time, the landing page was the get started page, which the website redirects to
• 61% of the time, the landing page was an atypical inflow page, which implies these are users entering via google search or direct link.
• We are getting solid traffic from kedro.org with the documentation button getting significant engagement

[astrojuanlu]

Themes that were evaluated so far:

• Lutra: the author recommended that we don't use it right now, it's undergoing a major redesign
• Furo: in good shape, less feature-rich
• Awesome Sphinx Theme: nice design baseline, better defaults, but some maintainability problems https://github.com/kai687/sphinxawesome-theme/issues/1586

Maybe we should go for Furo and borrow some things from Awesome Sphinx Theme.

[stichbury]

Just to note that I've closed a docs ticket to introduce a dark theme (https://github.com/kedro-org/kedro/issues/3179) but that it should be a consideration of the redesign when that happens.

[stichbury]

Also to note that redesign and light/dark theming should take into account that the docs are also rendered on GitHub which has potential for complication as we see in https://github.com/kedro-org/kedro/issues/3416.

[astrojuanlu]

Another theme to consider: https://github.com/lepture/shibuya

[astrojuanlu]

This is a framework issue even if it's in the Viz project.

[astrojuanlu]

Another UX issue that often bothers me: H2 and H3 have the exact same size.

[astrojuanlu]

In fact, this is a kedro-sphinx-theme issue now.

[astrojuanlu]

The RTD ad covers the "Next" button 😱

[humitos]

The RTD ad covers the "Next" button 😱

There are two different paths here to solve this issue:

1. Opt-out from Ads: https://docs.readthedocs.io/en/stable/advertising/ethical-advertising.html#opting-out
2. Use an explicit placement for the ad in your theme: https://docs.readthedocs.io/en/stable/advertising/ad-customization.html#controlling-the-placement-of-an-ad

Let me know if them works for your use case.

[astrojuanlu]

Thanks for the pointers @humitos. I don't think we're opting out for now, and to find a better placement we need to do some design work anyway. We might try to solve this more urgently though and then do a full redesign at a later stage.