Skip to content

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

Merged
erlend-aasland merged 1 commit intopython:mainfrom
erlend-aasland:clinic-docs/tutorial-no-list
Jul 26, 2023
Merged

Docs: Remove the numbered steps from the Argument Clinic tutorial#107203
erlend-aasland merged 1 commit intopython:mainfrom
erlend-aasland:clinic-docs/tutorial-no-list

Conversation

@erlend-aasland
Copy link
Copy Markdown
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
Copy Markdown
Contributor Author

erlend-aasland commented Jul 24, 2023

@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
Copy Markdown
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
Copy Markdown
Contributor Author

erlend-aasland commented Jul 26, 2023

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
Copy Markdown
Contributor

miss-islington commented Jul 26, 2023

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
Copy Markdown
Contributor

miss-islington commented Jul 26, 2023

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
Copy Markdown

bedevere-bot commented Jul 26, 2023

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 <erlend@python.org>
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 <erlend@python.org>
@bedevere-bot
Copy link
Copy Markdown

bedevere-bot commented Jul 26, 2023

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

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

1 more reviewer

@evildmp evildmp evildmp approved these changes

Reviewers whose approvals may not affect merge requirements

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