Interim design changes to accommodate documentation subprojects (datasets & Viz)

[stichbury]

Description (edit 07/09 as part of ticket clean up)

As part of the subproject documentation work in kedro#2600 we need to consider some layout and content changes.

Content changes (minor): Link changes between projects, so if a page in Kedro docs links to datasets or viz docs, the link is updated when the subproject docs are published. This is covered in #3015

Layout changes (major): This is a more significant task because it resolves navigation between projects and facilitates ease of use of the entire set of docs.

I'm mindful that #1474 will have to take into account navigation but I don't want to couple the subproject work to a major overhaul of docs design and UX. For now, it's important to take the subproject work forward as this is a higher priority for us as a working team than the look and feel of the docs (from user research we know this isn't the highest priority).

cc for info @astrojuanlu @tynandebold @stephkaiser

[stichbury]

Edit 07/09 -- this is pretty complicated and I don't advise reading it.

Read only if you want to see how much Jo struggles with UI

So this is what I've considered as I've investigated the URL structure we'd get with the RTD subprojects, and as I understand it, we can use aliases to set up a set of docs with a shared prefix, so something like this (see https://docs.readthedocs.io/en/stable/subprojects.html#sharing-a-custom-domain for more).

* Kedro framework: https://docs.kedro.org/en/stable/. <--what we have now
* Kedro Viz: https://docs.kedro.org/projects/kedro-viz/en/stable/
* Datasets: https://docs.kedro.org/projects/kedro-datasets/en/stable/

But what does this look like in practice if a user navigates to the framework docs?

• How do they find the Viz docs?
• Does navigation to https://docs.kedro.org/projects/kedro-viz/en/stable/ mean that the Kedro framework docs ToC is unavailable?

What we ideally want the users to have access to is either:

1. The Kedro docs embed a section of the ToC for Viz and Datasets

• Learn about Kedro

  • Introduction to Kedro
  • First steps

• Tutorial and basic Kedro usage

  • Next steps: Tutorial
  • Visualisation with Kedro-Viz
  • Experiment tracking in Kedro-Viz
  • Kedro for notebook users
  • etc

• Introduction to Kedro-Viz (this is stored at https://docs.kedro.org/projects/kedro-viz/en/stable/introduction.html)

  • Section of Viz docs WHEN YOU READ THIS THE TOC OPENS OUT BUT DOESN'T REPLACE THE TOC FOR FRAMEWORK
    • Page of Viz docs
    • Another page

• More Kedro docs in a section e.g. "Extend Kedro"

  • Page (back to docs at https://docs.kedro.org/en/stable/extend_kedro/index.html)
  • Page

• Dataset docs (https://docs.kedro.org/projects/kedro-datasets/en/stable/introduction.html)

• Section of dataset docs WHEN YOU READ THIS SECTION THE TOC OPENS OUT BUT DOESN'T REPLACE THE TOC FOR FRAMEWORK
  - Page of dataset docs
  - Another page

• More Kedro docs in a section e.g. "Deploy Kedro"

  • Page (back to docs at https://docs.kedro.org/en/stable/deployment/index.html)
  • Page

2. The Kedro docs ToC includes separate sections for Viz and Datasets

On first navigation to docs.kedro.org you see in the left ToC:

• • Kedro
• • Kedro Viz
• • Kedro Datasets

Each is expandable. Clicking on "Kedro" it opens all the framework docs but retains the other expandable sections for Viz/Datasets at the bottom:

• Learn about Kedro
  • Introduction to Kedro
  • First steps

... All the Kedro docs

• • Kedro-Viz (this is stored at https://docs.kedro.org/projects/kedro-viz/en/stable/introduction.html)
    • Section of Viz docs WHEN YOU READ THIS THE TOC OPENS OUT BUT DOESN'T REPLACE THE TOC FOR FRAMEWORK
      • Page of Viz docs
      • Another page
• • Dataset docs (https://docs.kedro.org/projects/kedro-datasets/en/stable/introduction.html)

• Section of dataset docs WHEN YOU READ THIS SECTION THE TOC OPENS OUT BUT DOESN'T REPLACE THE TOC FOR FRAMEWORK
  - Page of dataset docs
  - Another page

---

This is similar but it doesn't mix the docs into one ToC. It adds the ToCs together into one "super ToC" which expands/collapses depending on which docset you are using but retains access to the ToCs of the others.

3. Less than ideal

This is the option where n first navigation to docs.kedro.org you see just the framework docs and there are separate navigation elements to get to the other ToCs, and between them each.

[stichbury]

@astrojuanlu @tynandebold I think this is the challenge, but let me know if there is a better way of looking at this (I can scribble some sketches) as I find it hard to visualise it.

[astrojuanlu]

This is what I had in mind (please excuse the hastily drawn diagrams):

So:

But what does this look like in practice if a user navigates to the framework docs?

• How do they find the Viz docs?

They're always visible on top

• Does navigation to https://docs.kedro.org/projects/kedro-viz/en/stable/ mean that the Kedro framework docs ToC is unavailable?

Yes.

This is just one proposal, take it with a grain of salt.

[stichbury]

Ah, OK, nice. So addition of the new top nav is basically what this ticket needs to solve?

[astrojuanlu]

If we think this is a good navigation architecture, we can look into the technical feasibility, and I think Sphinx + RTD subprojects should work (I've seen other projects do similar things). When we're positive this is the direction we want to take, we probably need a hand from design to make this layout a reality, using any of the 3-column themes mentioned in #4257.

[astrojuanlu]

Essentially this enables Viz to have their own docs living on the kedro-viz repository, same as we did with kedro-datasets already (and I argue makes them more discoverable too, since they'd be always visible on the top bar). In exchange, they would not be in the Framework ToC anymore, and we'll need to shuffle some content around.

[stichbury]

Exactly! I'm more than happy with moving the docs back into separate repos as I think that gives each project more autonomy in terms of release cadence. Also good because it makes the layout of the framework ToC shorter and more logical.

I am less enthusiastic about coupling in this work with #4257 though because that's a big chunk of work/time and involves a lot more than a horizontal navigation bar. I'd like this to be quite separate otherwise it won't happen for ages because of the time required and research needed.

[astrojuanlu]

Good point. Let's give some thought at what the Minimum Viable Change looks like here.

[stichbury]

This will need to move into the next sprint as both @tynandebold and I are away from 28/08 - 04/09 but we should consider it then.

[stichbury]

I'm closing this ticket as this was for the design work. There's a separate ticket for the implementation and PR is here.