Further enhancements to spaceflights tutorial following onboarding reviews

[stichbury]

There are a few extra tweaks we can make to the spaceflights tutorial following onboarding by @amandakys and @astrojuanlu and this ticket captures those. I'll expand them more fully in due course, but want to record the basics here.

From @amandakys

• Reduce branches so the flow of the tutorial is linear for different reader types (windows vs MacOS etc)
• Reduce notes because they are distracting (or hide the details)
• Make the expandable code sections consistent (everything or nothing)
• Consider an "express tutorial" for those using the Starter, rather than the branching approach which tells the starter users not to bother copying code, repeatedly.
• Add tooltips for Kedro terminology (Sphinx extension)
• Talk about conda knowledge as part of pre-requisites
• Explain how to find out Kedro version
• Clarify what an ipython session looks like
• Remove note about adding the pipeline to the registry (unless already done?)
• Consider how to integrate viz since graphics aren't that intuitive

From @astrojuanlu Quite a lot to think about, but one thing I definitely need to fix immediately:

• https://kedro.readthedocs.io/en/latest/get_started/summary.html says "Following the tutorial, you’ll learn how to visualise a Kedro project and learn more about combining Kedro with a Jupyter notebook." but the tutorial doesn't do that -- the notebook stuff is separate.

<I'll record the rest here shortly>

[astrojuanlu]

I'm working on writing down further enhancements to the spaceflights tutorial, as well as various bits I'm finding about the CLI, hence I added this issue to the current sprint. However, other tasks have higher priority, and as such implementing those enhancements will likely need to be done at a later stage.

[astrojuanlu]

Some notes below. My north star is the 4-quadrant framework Diátaxis.

(Disclaimer: All statements below are my opinion and can be debated)

First of all, the website contains 2 calls to action that sound very similar: "Get started" and "Take the Tutorial". The two overlap a bit, because they both cover basic commands like kedro new, starters, kedro run and so on, but the spaceflights tutorial is of course much more comprehensive, and the "Get started" section contains lots of explanations that somehow get in the way. Wondering if this landing could be simplified. The "Get started" section is not in scope for this issue though, so I'll skip to the spaceflights tutorial.

I'm going to assume that the target audience for the tutorial are

• Data scientists (hence knowledge about machine learning, statistics, lightweight coding)
• with Python experience (basic syntax, data manipulation with pandas)
• that don't know anything about Kedro but want to learn more (hence they're hopefully motivated to complete the tutorial from beginning to end)
• and are confident with the terminal of their operating system of choice (although we should narrow this down to a UNIX-like terminal like WSL2 for Windows + Bash on Linux + ZSH on macOS).

In general, I think the tutorial contains too many explanations that are a bit distracting, and many optional parts that made me think a bit too much and could perhaps belong to a how-to guide. Now, some specific things:

• The tutorial kind of assumes an IDE (rather than, say JupyterLab). We should probably make that more explicit, and point readers towards other Jupyter-friendly pages (Kedro and Jupyter Notebooks, Kedro as a data registry).
• The optional git part suggests Gitflow, but then the Flatiron blog post that comes right before doesn't mention it. Gitflow is a quite heavy workflow and most beginners will either pick something simple for their personal projects or adopt whatever their team is using, so I think we should be less opinionated about it. Also, many people using GUIs for git (like VS Code, Gitkraken and such) so maybe we don't even need to include a micro crash course on git.
• In any case, I think instructing readers to either (1) commit their changes at the end of every chapter or (2) doing everything from the GitHub interface (potentially using Gitpod or Codespaces for terminal access) would be a nice touch.
• There are some deprecated commands mentioned there, like kedro lint, kedro build-docs and so on. We should replace or remove those.
• The part that covers the config doesn't explain whether credentials.yml ends up being tracked in version control or not, we could clarify that a bit.
• "Ask the community for help" and the FAQ shouldn't be part of the tutorial, but top-level pages.
• "Bruce Philp and Guilherme Braccialli are the brains behind a layered data-engineering convention" but then Joel's blog post on Medium never mentions them.
• Some of the commands include absolute paths. We should either reduce those to a minimum (since they assume a given operating system).
• Some types are not well specified, for example name: str = None should be name: str | None = None or name: Optional[str] = None.
• Initially I found it surprising that the default behavior is to not write the datasets to disk (until they're manually registered). Makes the default behavior resemble a "dry run", since there is no output. This is not a criticism of the tutorial itself, just an observation.
• The first time the __default__ pipeline is mentioned, it's not explained - I only understood it at the very end. If we don't want to explain it at that point, we could as well remove it.
• The "modular pipelines" chapter introduces kedro viz for the first time. We could be more purposeful about it.
• I proposed obliterating .egg files from Kedro at #2273.
• The tutorial could end with a "where to go next" that points users towards other useful parts of the documentation.

[stichbury]

Just to note that #2273 is now purely about any changes to the framework to stop producing eggs. This ticket will take care of any associated docs changes.

[astrojuanlu]

One more: the default project name for the spaceflights starter is Spaceflights, and this might cause confusion (see https://github.com/kedro-org/kedro/pull/2364).

[stichbury]

This comment records work done and work to do.

Work done

• Reordered pages to keep hands-on separate from concepts

• Renamed sections of docs to make the on-boarding more linear, particularly in the get started phase

• Removed TL;DR summary page in the get started section and added those sections where appropriate

• Revised the copy in the page about getting started to push the iris example out of the limelight

• Removed the section about Git in the tutorial

• Removed the option to copy/paste code — this is now an express tutorial without any actions required from the reader (except thought)

• Removed mention of "command line" in docs and kept a consistent "terminal" or "terminal window" throughout

• Added pipenv and venv back to installation/setup guide (alongside conda) (@astrojuanlu please can you review?)

• Reviewed all the notes and work out if they're all needed. Likewise all the explanatory text that may "get in the way"

• Made the workflow more explicit (we assume the reader isn't using a notebook, so should say so)

• Removed deprecated commands like Kedro lint, Kedro build-reqs

• Checked all the file paths

• Made the "What you've learned" and "where to go next?" sections more explicit

• Renamed throughout from "Kedro Tutorial" to "Spaceflights" to correspond with default name for starter project

• Removed mention of eggs 🥚

• Work to do

• Clarify whether credentials.yml is tracked in version control