Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork33.3k
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
Uh oh!
There was an error while loading.Please reload this page.
Conversation
c695ec3 to896053bCompareUh oh!
There was an error while loading.Please reload this page.
CAM-Gerlach left a comment• edited by erlend-aasland
Loading Uh oh!
There was an error while loading.Please reload this page.
edited by erlend-aasland
Uh oh!
There was an error while loading.Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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!
Uh oh!
There was an error while loading.Please reload this page.
erlend-aasland commentedJul 20, 2022
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 commentedJul 20, 2022
Absolutely, but Diátaxis explicitly recommends such headings:https://diataxis.fr/how-to-guides/#pay-attention-to-naming |
erlend-aasland commentedJul 21, 2022 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
Regarding the "How to" prefix; |
CAM-Gerlach commentedJul 22, 2022
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 commentedJul 22, 2022
I guess you're right; that makes sense. I'd still like to put this on hold until after the workshop. |
erlend-aasland commentedJul 26, 2022
Here's how Django has organised their How To chapter: |
erlend-aasland commentedAug 18, 2022
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. |
Uh oh!
There was an error while loading.Please reload this page.
Fixes#94635