Movatterモバイル変換


[0]ホーム

URL:


Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

gh-94635: Normalise sqlite3 doc headings#94677

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 ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Closed

Conversation

@erlend-aasland
Copy link
Contributor

@erlend-aaslanderlend-aasland commentedJul 7, 2022
edited
Loading

Fixes#94635

Copy link
Member

@CAM-GerlachCAM-Gerlach left a comment
edited by erlend-aasland
Loading

Choose a reason for hiding this comment

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

  • Per the devguide,

    In the Python documentation, the use of sentence case in section titles is preferable, but consistency within a unit is more important than following this rule. If you add a section to a chapter where most sections are in title case, you can either convert all titles to sentence case or use the dominant style in the new section title.

    Since around half or more of the tiles are already sentence case, if we're going to change it, it makes sense to do so to the preferred style.

  • I'm not sure adding the "How to" prefix is necessary on titles that already are framed as tasks, since it is somewhat redundant and repetitive, especially if/when the supersection title is changed to "How-to"—it is inherent than sections directly underneath a "How to" section describe "How to" do something.

  • While you're at it and touching these anyway, youcould normalize it to use thestandard heading levels in the devguide—basically, just moving everything up a level, IIUC. But that's strictly optional, of course.

Other than that, this seems okay, assuming the plan is to move "Default Adapters and Converters" and "Adapter and Converter Recipes", etc., under their appropriate "How-to" sections ("Adapt..." and "Convert...") in the followup PR.

Thanks!

@erlend-aaslanderlend-aasland marked this pull request as draftJuly 14, 2022 22:25
@erlend-aasland
Copy link
ContributorAuthor

While you're at it and touching these anyway, you could normalize it to use thestandard heading levels in the devguide—basically, just moving everything up a level, IIUC. But that's strictly optional, of course.

I'm planning to address that in a separate PR. Let's do the headings first; I want these doc PRs to be concise.

@erlend-aasland
Copy link
ContributorAuthor

I'm not sure adding the "How to" prefix is necessary on titles that already are framed as tasks, since it is somewhat redundant and repetitive, especially if/when the supersection title is changed to "How-to"—it is inherent than sections directly underneath a "How to" section describe "How to" do something.

Absolutely, but Diátaxis explicitly recommends such headings:https://diataxis.fr/how-to-guides/#pay-attention-to-naming

@erlend-aaslanderlend-aasland marked this pull request as ready for reviewJuly 20, 2022 22:21
@erlend-aasland
Copy link
ContributorAuthor

erlend-aasland commentedJul 21, 2022
edited
Loading

Regarding the "How to" prefix;perhaps we should put this PR on hold until we're through the Diátaxis workshop in August. There is no hurry to get this done anyways.

ezio-melotti reacted with thumbs up emoji

@erlend-aaslanderlend-aasland marked this pull request as draftJuly 21, 2022 19:25
@CAM-Gerlach
Copy link
Member

Absolutely, but Diátaxis explicitly recommends such headings:diataxis.fr/how-to-guides/#pay-attention-to-naming

Right, but that's for top-level pagetitles, and the section headings would still be worded in task-oriented "how to" form (e.g. "(How to) adapt Python types to custom SQLite values", rather than the proscribed "Adapting Python types to custom SQLite values" or "Python-SQLite type conversion", with the "How to" wording as the top-level parent section, just not also repeated again in every sub-section title underneath it.

erlend-aasland reacted with thumbs up emoji

@erlend-aasland
Copy link
ContributorAuthor

I guess you're right; that makes sense. I'd still like to put this on hold until after the workshop.

CAM-Gerlach reacted with thumbs up emoji

@erlend-aasland
Copy link
ContributorAuthor

Here's how Django has organised their How To chapter:

https://docs.djangoproject.com/en/4.0/howto/

@erlend-aasland
Copy link
ContributorAuthor

Closing this, as most of the work has been done in other PR's. If we need to tweak headings, we can do so on a case-by-case basis.

Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment

Reviewers

@CAM-GerlachCAM-GerlachCAM-Gerlach left review comments

@ezio-melottiezio-melottiezio-melotti approved these changes

@berkerpeksagberkerpeksagAwaiting requested review from berkerpeksagberkerpeksag is a code owner

Assignees

No one assigned

Labels

awaiting mergeDO-NOT-MERGEdocsDocumentation in the Doc dirneeds backport to 3.10only security fixesneeds backport to 3.11only security fixesskip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Restructure the sqlite3 docs table-of-contents

4 participants

@erlend-aasland@CAM-Gerlach@ezio-melotti@bedevere-bot

[8]ページ先頭

©2009-2025 Movatter.jp