Skip to content

Docs: Remove the numbered steps from the Argument Clinic tutorial #107203

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 1 commit into from
Jul 26, 2023
Merged

Docs: Remove the numbered steps from the Argument Clinic tutorial #107203

merged 1 commit into from
Jul 26, 2023

Conversation

erlend-aasland
Copy link
Contributor

@erlend-aasland erlend-aasland commented Jul 24, 2023 •
edited by github-actions bot
Loading

@bedevere-bot bedevere-bot added the docs Documentation in the Doc dir label Jul 24, 2023
@erlend-aasland
Copy link
Contributor Author

@ezio-melotti, @AlexWaygood: I never liked much the numbered steps in the clinic tutorial. I think we should structure it as one body of prose, and focus on improving that text according to Diátaxis principles.

Perhaps we should create an issue for this, as this will only be the first of many steps in improving the tutorial.

This PR mostly just removes the numbered list (hence the big diff), and it adds a few links to some of the howtos. That latter part could have been a separate PR, though.

evildmp
evildmp approved these changes Jul 26, 2023
View reviewed changes
Copy link
Contributor

@evildmp evildmp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sections affected feel like they flow better as a result of this.

I think a subsequent improvement on this document could simply trim words, so that sentences and paragraphs are shorter, which would also help it move well.

@erlend-aasland
Copy link
Contributor Author

The sections affected feel like they flow better as a result of this.

Thanks for the review!

I think a subsequent improvement on this document could simply trim words, so that sentences and paragraphs are shorter, which would also help it move well.

Yes, this is the first of very many PRs for the clinic tutorial 😀 I'll focus more on wording and phrasing in the follow-up PRs.

@erlend-aasland erlend-aasland marked this pull request as ready for review July 26, 2023 10:55
@erlend-aasland erlend-aasland merged commit 5923955 into python:main Jul 26, 2023
@miss-islington
Copy link
Contributor

Thanks @erlend-aasland for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

@erlend-aasland erlend-aasland deleted the clinic-docs/tutorial-no-list branch July 26, 2023 20:54
@miss-islington
Copy link
Contributor

Sorry, @erlend-aasland, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 592395577c679543d899e68a3cff538b8b4df80d 3.11

@bedevere-bot
Copy link

GH-107317 is a backport of this pull request to the 3.12 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.12 only security fixes label Jul 26, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jul 26, 2023
@erlend-aasland @miss-islington
Docs: Remove the numbered steps from the Argument Clinic tutorial (py…
388661a 
…thonGH-107203)

Instead, order the tutorial as one body of prose, making it easier to
align the tutorial according to Diátaxis principles.
(cherry picked from commit 5923955)

Co-authored-by: Erlend E. Aasland <[email protected]>
erlend-aasland added a commit that referenced this pull request Jul 26, 2023
@miss-islington @erlend-aasland
[3.12] Docs: Remove the numbered steps from the Argument Clinic tutor…
6bbcd79 
…ial (GH-107203) (#107317)

Instead, order the tutorial as one body of prose, making it easier to
align the tutorial according to Diátaxis principles.

(cherry picked from commit 5923955)

Co-authored-by: Erlend E. Aasland <[email protected]>
@bedevere-bot
Copy link

GH-107319 is a backport of this pull request to the 3.11 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.11 only security fixes label Jul 26, 2023
erlend-aasland added a commit to erlend-aasland/cpython that referenced this pull request Jul 26, 2023
@erlend-aasland
[3.11] Docs: Remove the numbered steps from the Argument Clinic tutor…
efc517c 
…ial (python#107203)

Instead, order the tutorial as one body of prose, making it easier to
align the tutorial according to Diátaxis principles.

(cherry picked from commit 5923955)
erlend-aasland added a commit that referenced this pull request Jul 26, 2023
@erlend-aasland
[3.11] Docs: Remove the numbered steps from the Argument Clinic tutor…
55edee2 
…ial (#107203) (#107319)

Instead, order the tutorial as one body of prose, making it easier to
align the tutorial according to Diátaxis principles.

(cherry picked from commit 5923955)
jtcave pushed a commit to jtcave/cpython that referenced this pull request Jul 27, 2023
@erlend-aasland @jtcave
Docs: Remove the numbered steps from the Argument Clinic tutorial (py…
b1841f4 
…thon#107203)

Instead, order the tutorial as one body of prose, making it easier to
align the tutorial according to Diátaxis principles.
erlend-aasland added a commit to erlend-aasland/devguide that referenced this pull request Sep 8, 2023
@erlend-aasland
Docs: Remove the numbered steps from the Argument Clinic tutorial (py…
9ffba19 
…thon/cpython#107203)

Instead, order the tutorial as one body of prose, making it easier to
align the tutorial according to Diátaxis principles.
AA-Turner pushed a commit to AA-Turner/devguide that referenced this pull request Sep 13, 2023
@erlend-aasland
Docs: Remove the numbered steps from the Argument Clinic tutorial (py…
f4d2138 
…thon/cpython#107203)

Instead, order the tutorial as one body of prose, making it easier to
align the tutorial according to Diátaxis principles.
erlend-aasland added a commit to python/devguide that referenced this pull request Sep 26, 2023
@erlend-aasland
Docs: Remove the numbered steps from the Argument Clinic tutorial (py…
ce97b52 
…thon/cpython#107203)

Instead, order the tutorial as one body of prose, making it easier to
align the tutorial according to Diátaxis principles.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@evildmp evildmp evildmp approved these changes

@ezio-melotti ezio-melotti Awaiting requested review from ezio-melotti

Assignees

@erlend-aasland erlend-aasland

Labels
docs Documentation in the Doc dir skip issue skip news
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@erlend-aasland @miss-islington @bedevere-bot @evildmp