Changing docs for trivial issues

[slateny]

There's this open issue right now on British vs American spelling:

python/cpython#82221

In the past, there's been some merged PRs on similar smallish consistency/grammar issues:

python/cpython#2787
python/cpython#25985

However, there are also these other comments that seem to resist against trivial changes:

python/cpython#58372 (comment)
python/cpython#62480 (comment)

The sense that I'm getting is that trivial / minor grammatical / consistency issues are generally not considered if it's either unreported, too large such that it'll take more core dev reviewing time than it's worth in improvement, or touches on somewhat historical docs. Would this be an accurate summary on whether to consider committing small changes?

[CAM-Gerlach]

(Minor sidenote: Just FYI, to make it easier for others to review the cases you mentioned, can you make them actual inline Markdown links, or at least just inline text or in a bulletted list, which would get linked automatically, instead of code blocks? And to note, you can automatically create inline links to other GitHub issues with helpful popup summaries just by writing /#NNNN , e.g. python/cpython#82221 , python/cpython#2787 python/cpython#25985 , etc.)

[slateny]

Yep, I can swap them no problem, I just didn't want auto references in the linked PRs/issues since I felt that these aren't directly related to the issues/PRs, and I'm just grabbing them as an example for the question I had. But cross referencing might be useful actually if someone comes along with the same questions as me

[CAM-Gerlach]

I see; I thought it wouldn't cross reference if you provide a full link, but maybe you know better than I, heh.

[JelleZijlstra]

I think small improvements are OK, but they do really need to be improvements. If it's unclear whether the change really improves things, I'd rather stick to the status quo.

My thoughts on your examples:

• writeable vs writable: the conclusion was that both are valid spellings, so we should just stick with the one we already use
• color vs colour on IDLE: I think we should follow Wikipedia's rule (https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style#National_varieties_of_English), which is that the original author of a document gets to pick the variety of English used, and then we stick with that. So I would not have approved a wholesale change of "colour" to "color".
• uppercase vs upper-case: didn't look too closely but seems fine to improve the spelling

[willingc]

I agree with @JelleZijlstra's approach re: the examples.

It would probably make sense to update the devguide's docs sections or use that to create a docs style guide. It would be helpful so that people would know the preferred style.

[CAM-Gerlach]

color vs colour on IDLE: I think we should follow Wikipedia's rule, which is that the original author of a document gets to pick the variety of English used, and then we stick with that. So I would not have approved a wholesale change of "colour" to "color".

This is the rule we generally follow on the PEPs repo as well, since we have both AmE and BrE natives, along with avoiding verbiage specific to one or the other that could potentially impede clear understanding by all.

It would probably make sense to update the devguide's docs sections or use that to create a docs style guide. It would be helpful so that people would know the preferred style.

So long as there's some consensus on what the style should be (or at least that should be one), I'd be happy to help with such effort, given I have some experience with various docs style guides, and writing our own detailed one for the Spyder documentation projects.

[willingc]

Hi @slateny, Thank you for your interest and effort in contributing to CPython and its docs. I appreciate your effort. Would you like triage privileges on this repo?

[slateny]

Hi @slateny, Thank you for your interest and effort in contributing to CPython and its docs. I appreciate your effort. Would you like triage privileges on this repo?

Thanks Carol, Irit's actually opened a request for me here already :)

[CAM-Gerlach]

I'm not sure whether or not becoming a CPython triager grants those same permissions on this repo? I think I'd have to be an admin to check...

[AlexWaygood]

I'm not sure whether or not becoming a CPython triager grants those same permissions on this repo? I think I'd have to be an admin to check...

I'm a CPython triager and I appear to have no special privileges on this repo, so, seems like it doesn't :)

[willingc]

@AlexWaygood I just added all of the cpython triagers to this repo. Could you please see if you now have triage privileges? Thanks.

[willingc]

@CAM-Gerlach added the CPython triagers to this repo too.

[AlexWaygood]

@AlexWaygood I just added all of the cpython triagers to this repo. Could you please see if you now have triage privileges? Thanks.

I do! How exciting :D

[slateny]

Would it be fair to say that these are generally true?

• if there's two near identical spellings / grammar quirks (hyphenation, AmE/BrE), then the current majority in the article should be applied, otherwise if there's a rough split then the older spelling holds. However, there doesn't need to be consistency between different articles
• changes that don't greatly affect readability (maybe wording changes like, 'a file that's not standard' vs 'a non-standard file') are unneeded unless to fix consistency as above

I think maybe some justification on why certain rules are in place would be nice as well, if a style guide is made, something like 'spelling consistency within an article is encouraged as it's easier to do a keyword search on a page'