classification
Title: Hyphenation suggestions - floating-point/floating point
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Andrew.Smith, Matthew.Johnson, docs@python, eli.bendersky, eric.araujo, joenapnap, petri.lehtinen, poq
Priority: normal Keywords: patch

Created on 2012-03-01 12:25 by joenapnap, last changed 2012-03-02 05:06 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
patch.diff joenapnap, 2012-03-01 12:25 fixes some hyphens review
Messages (8)
msg154688 - (view) Author: John Napster (joenapnap) Date: 2012-03-01 12:25
This patch fixes some small grammar things in the docs. Hope you like my contribution.
msg154691 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2012-03-01 13:07
See also #13868 by Retro.
msg154694 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-03-01 14:10
John, thanks for the contribution, however this is not a valid fix. 

See the Wikipedia page for floating point: http://en.wikipedia.org/wiki/Floating_point

No dash! 

There is no need to go over the Python docs fixing such "mistakes". If you have time to contribute to Python, there's *plenty* of opportunities to do so in a useful way.
msg154696 - (view) Author: Matthew Johnson (Matthew.Johnson) Date: 2012-03-01 14:54
I think he's right to fix those "mistakes". Just see the first sentence @ http://docs.python.org/tutorial/floatingpoint.html#floating-point-arithmetic-issues-and-limitations

It reads: "Floating-point numbers are represented in [...]"

So as you can see, there are places in the docs where the hyphen/dash is there, other places where it is not. I, personally, don't get the whole "some places yes, someplaces no" philosophy. I think the patch should be applied. I think he was just trying to make some consistentcy in the docs as his first contribution.

I must also point out that I don't understand the whole "some places title-case, other places sentence-case" titles in the docs. It's kind of confusing.

What are your thoughts about all this?
msg154708 - (view) Author: (poq) Date: 2012-03-01 18:08
It is generally considered more correct to write "floating-point number", because "floating-point" is a compound adjective here. The hyphen clarifies that it should be parsed as ((floating point) number) instead of (floating (point number)).

However, in practice "floating point number" is also commonly used. I completely agree with Eli that this is just nitpicking, and not a productive use of Python developers' time.
msg154709 - (view) Author: Brian Curtin (brian.curtin) * (Python committer) Date: 2012-03-01 18:20
Hyphenation changes are not going to be made unless the current text is actually incorrect, confusing, or leads to people misunderstanding what is meant.
msg154710 - (view) Author: Andrew Smith (Andrew.Smith) Date: 2012-03-01 19:13
I think he was trying to say that there is inconsistency in the docs... And since you guys are all about consistency... Why the punch below the belt?
msg154729 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-03-02 05:06
Python has a lot of known and unknown bugs that need to be fixed, many missing features needing to be implemented, and a lot of room for improvement in its documentation.  That’s why we welcome people who want to help.

You’re not the first one to propose a trivial typographic patch that is rejected.  I’m writing this long-ish message to serve as a reference for future rejections.

Maybe you thought it would be a risk-free way to become a contributor, but as it turns out, this kind of patches is not helpful.  All Python developers are volunteers, and we review bugs and patches on our limited free time.  It is worthwhile to fix clear errors, ambiguities, outdated facts and wrong advice in the documentation; it is not worthwhile to add or remove a few commas and hyphens just for consistency’s sake.  (Moreover, hyphens in English don’t have rules as clear as we commonly think, like poq pointed.)

There is no “some places title-case, other places sentence-case” philosophy; different people wrote various parts of the documentation, and we just live with it.  We fix bugs, improve code, add examples, think about missing features, read specifications, reply to email, improve wordings; we just don’t have the time to care about questionable changes that don’t add any value for us or our users.  Consistency is a design principle; it does not mean obsessive polishing.  There are also other principles that are equally valid, and also pure pragmatic constraints.

John and Matthew, you are more than welcome to report bugs you find, or to work on fixing a bug, from the long list of bugs that really would improve people’s life when fixed.  If you are unsure about the process or about your patch, please join http://mail.python.org/mailman/listinfo/core-mentorship mailing list to ask any question you might have: we will help you.

Hope this clarifies things without hurting anyone’s feelings.
History
Date User Action Args
2012-03-02 05:06:05eric.araujosetnosy: + eric.araujo
messages: + msg154729
2012-03-01 19:14:46brian.curtinsetnosy: - brian.curtin
2012-03-01 19:13:10Andrew.Smithsetnosy: + Andrew.Smith
messages: + msg154710
2012-03-01 18:20:29brian.curtinsetstatus: open -> closed

title: my little contribution to the docs -> Hyphenation suggestions - floating-point/floating point
nosy: + brian.curtin

messages: + msg154709
resolution: rejected
stage: patch review -> resolved
2012-03-01 18:08:44poqsetnosy: + poq
messages: + msg154708
2012-03-01 14:54:49Matthew.Johnsonsetnosy: + Matthew.Johnson
messages: + msg154696
2012-03-01 14:10:06eli.benderskysetnosy: + eli.bendersky
messages: + msg154694
2012-03-01 13:07:00petri.lehtinensetnosy: + petri.lehtinen
messages: + msg154691
2012-03-01 12:32:13floxsetstage: patch review
versions: + Python 3.3
2012-03-01 12:25:25joenapnapcreate