gh-107432 Update Porting Python 2 Code to Python 3 how-to #107434
Conversation
https://docs.python.org/3/howto/pyporting.html#porting-python-2-code-to-python-3 was written for another time. In this patch: * material that frames Python 3 as "new" is removed * descriptions and directions have been trimmed
hugovk
added
needs backport to 3.11
| Porting Python 2 Code to Python 3 | ||
| ********************************* | ||
| ************************************* | ||
| How to port Python 2 Code to Python 3 |
There was a problem hiding this comment.
Not sure why we need to change the title
There was a problem hiding this comment.
Every genuine how-to guide should have a title "How to <xxx>" to signal clearly what its purpose and scope is.
In menus, the title can be shortened to "<xxx>". Eventually it means you can have a menu that looks like:
How to
Install
Deploy
Scale
etc. So the same clarity of purpose is recapitulated there.
An exception is when it might be clunky to use "how to" - for example I think that "Troubleshooting" is firstly rather less hideous than "How to troubleshoot" and secondly already implies that it's about taking action (in a way that "porting" does not).
"Porting Python 2 Code to Python 3" is ambiguous. Maybe it's not a how-to guide - maybe it's what I should read to find out why I should do that.
If you apply this logic to other documents in that HOWTO section, it becomes clear that many of them cannot be given "How to..." titles - because their content is definitely not how-to content. An example is the functional programming document, which is one that I think should find a different home, for that reason.
Paying close attention to titles is helpful for the clues it gives us about documentation, and sets down good markers for future work.
Co-authored-by: Jelle Zijlstra <[email protected]>
If it's a mostly historical document, it should not occupy precious space in the documentation, distracting attention from ones that are relevant. To achieve documentation of quality, nothing should be there that does not perform a useful function. If it is to stay, it should be maintained. |
IMO, that decision needs a broader audience. FWIW, I'm also in favour of archiving obsolete stuff and/or marking pages as historical. |
|
Let's merge this, and if someone wishes, please open a discussion about archiving at https://discuss.python.org/c/documentation/26. |
|
GH-108409 is a backport of this pull request to the 3.12 branch. |
|
GH-108410 is a backport of this pull request to the 3.11 branch. |
…onGH-107434) https://docs.python.org/3/howto/pyporting.htmlGH-porting-python-2-code-to-python-3 was written for another time. In this patch: - material that frames Python 3 as "new" is removed - descriptions and directions have been trimmed (cherry picked from commit 809ea7c) Co-authored-by: Daniele Procida <[email protected]>
…onGH-107434) https://docs.python.org/3/howto/pyporting.htmlGH-porting-python-2-code-to-python-3 was written for another time. In this patch: - material that frames Python 3 as "new" is removed - descriptions and directions have been trimmed (cherry picked from commit 809ea7c) Co-authored-by: Daniele Procida <[email protected]>
…107434) (#108409) gh-107432 Update Porting Python 2 Code to Python 3 how-to (GH-107434) https://docs.python.org/3/howto/pyporting.htmlGH-porting-python-2-code-to-python-3 was written for another time. In this patch: - material that frames Python 3 as "new" is removed - descriptions and directions have been trimmed (cherry picked from commit 809ea7c) Co-authored-by: Daniele Procida <[email protected]>
…107434) (#108410) https://docs.python.org/3/howto/pyporting.html was written for another time. In this patch: - material that frames Python 3 as "new" is removed - descriptions and directions have been trimmed (cherry picked from commit 809ea7c) Co-authored-by: Daniele Procida <[email protected]>
https://docs.python.org/3/howto/pyporting.html#porting-python-2-code-to-python-3 was written for another time. In this patch:
📚 Documentation preview 📚: https://cpython-previews--107434.org.readthedocs.build/