astrojuanlu
commented
8 months ago Some notes on the scope of this ticket. Adapted from @stichbury original comment:
Detailed description of some of the problems
[...]
- 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
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
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.
Some themes we could consider:
Also from kedro-org/kedro#2394 (from @astrojuanlu)
Possible approaches
Next steps
I need to discuss further with @stephkaiser and the broader team to evaluate available time from Design and beyond.