Investigate information architecture of current documentation

[antonymilne]

Written by @noklam in a draft issue. I made it into a full issue because I think it's a great point to raise and I agree a lot with what he says 😀

This may be related to the "Learning Curve" issue with Kedro. I have some sympathy for the users, especially with the template changes we have in different versions. For example, hooks.py is removed.

These information are documented somewhere, some are in docs, some are in RELEASE.md, it's easy for us to navigate but not so much for a complete beginner.

A rough idea is to have a document explain how users should interact with Kedro. These are the most common files that a user with modify when they are in a Kedro Project

(From most common to least common)

1. kedro run
2. catalog.yml & parameters.yml
3. global.yml
4. settings.yml
5. hooks.py (not exist anymore because of the removal of ProjectHook, but it's still a recommend way to put custom hook implementation
6. logging.yml
7. cli.py

[antonymilne]

@noklam mentioned when this was discussed during backlog grooming that our docs are organised by the kedro codebase rather than how a user might actually want to use the documentation. This is a great point I think. It reminded me of something I wrote in https://github.com/quantumblacklabs/private-kedro/issues/989 (internally accessible only so let me copy it here): we need to signpost to users what their "learning journey" through kedro is, i.e. where should they start, which concepts are for more advanced users, etc.

More exciting navigation

The docs are very big and I wonder if we could add some other useful (and potentially exciting and engaging) way to navigate them. I think that as a new user it’s actually pretty clear where to start, but what’s not so clear is how different concepts in kedro link together and what order you should learn things in. Since everything is arranged in a hierarchical way as sections, subsections, etc. it’s hard to understand how different bits of documentation relate.

Could we have one (or more) diagrams on the docs homepage? Very rough artist’s impression, in which I make stuff up and show why I’m not a designer:

Here blue boxes represent tutorials and grey boxes are key kedro concepts. You would be able to click on each box and it would take you to that bit of the documentation.

What would I like such diagram(s) to achieve?

• Helps a user plan and progress through their journey as they learn kedro and move on to progressively more advanced topics
• Gives an overview of and breaks down the available documentation in a way that is more understandable and engaging than a big tree of headings/subheadings
• Links concepts together in a way that can’t be done through the hierarchical docs structure
• Looks super cool, makes people think we’re cool and encourages them to read the documentation. Clicking on things is just more fun if it’s a nice button in a diagram rather than plain text

[noklam]

I was just in some kedro onboarding training today and have some more thoughts about this. When we introduce Kedro, we start with introducing different components, Data Catalog, parameters.yml, kedro-viz. These concepts do not resonate if you are from a notebook-driven development workflow. I am thinking the doc should be behavioral-driven. There will be some maintenance effort but I think this is a very important entry point for beginners.

I think it's almost like a FAQ style for data-scientist.

For example:

• How do I change a parameter? (Update parameters.yml or kedro run --params)
• How do I run part of the pipeline? (kedro run --pipeline=xxx)
• How can I work with a notebook? (kedro jupyter is not a complete answer to this, how would that workflow be like?)

[stichbury]

This is now a parent ticket for a range of short- and long-term activities to improve information presentation in the documentation.

Children:

• Information architecture: collapse table of contents? #2477
• Information architecture: Build a clear picture of docs usage through data #2478

[stichbury]

Closing this as it is now covered as part of user research/ongoing planning for changes to documentation in #2545