Skip to content

DOC: tutorials follow up to guide #27769

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

story645
Copy link
Member

@story645 story645 commented Feb 11, 2024

ETA: Following @timhoffm's suggestion, this pulls the tutorial content guidance from #26389 into this PR so it can be evaluated in conjunction with a rework of the index page.

In summary, this PR:

  • provides a content guideline + sample inline with the diátaxis guideline as tutorial as guided walk through
  • removes the links to the individual user guide documents because cross listing those documents as user guide pages and tutorials makes it very unclear what we consider a user guide versus a tutorial -> which hurts both:
    • discoverability -> it's unclear what sorta content is supposed to be on a page so hard to build intuition on what should be there
    • contributing -> it's unclear what kinda of contributions would be acceptable because the pages don't have a clear identity
  • replaces the custom gallery code with a gallery listing. In theory we can just go back to a readme page, but this (uses an unreleased feature of sphinx so requires a release, am adding dev here just to demo what page would look like)
  • moves the donut page to tutorials because it's showing a couple of things: how to make a donut chart and also how to annotate it - in an explanatory linear manner, talking the reader through each stage of the process. That's roughly the delineation between tutorial and example/how-to according to diataxes(https://diataxis.fr/tutorials/)

remove user guide tutorials and add annotation to tutorials landing page
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant