Add initial contributor and style guide #307
Conversation
There was a problem hiding this comment.
This generally looks good to me - just one substantive comment regarding the exact wording of the guide's purpose.
What's currently there isn't wrong, but I suspect it may confuse some readers due to the whole "distributions" vs "Python distributions" vs "distribution packages" ambiguity problem.
source/contribute.rst
Outdated
| The purpose of the |PyPUG| is | ||
|
|
||
| to be the authoritative resource on how to package, publish and install | ||
| Python distributions using current tools |
There was a problem hiding this comment.
We conceded the "distributions" terminology debate a while back, so I'd suggest rephrasing this to:
to be the authoritative resource on how to define, build, publish, and install Python distribution packages using current tools
That rephrasing also avoids the ambiguity with Python distributions like ActivePython, EPD/Canopy, Anaconda/miniconda, pyenv, Linux packages, Mac homebrew, etc
I also considered reordering the subactivities in order of the number of people that engage in them, from most common (installing packages published by others) to least common (publishing your own packages), but that phrasing was much more awkward than using the chronological order of the publishing process. Instead, I just split "package" into two subtasks ("define" and "build") so it wasn't be used as both a noun and a verb in the same sentence.
There was a problem hiding this comment.
In this instance, I'd be inclined to use the term "Python projects" in place of "Python distribution packages". At this point, the reader can be assumed to have a limited feel for the subtleties of technical terms like "distribution package", and "project", while ambiguous, probably corresponds most closely with the reader's intuitive understanding.
There was a problem hiding this comment.
+1 for "Python projects", which would give:
to be the authoritative resource on how to package, publish, and install Python projects using current tools
(since "package" should be in there somewhere, and with the noun form removed the sentence, we're free to use it as a verb again)
There was a problem hiding this comment.
I was quoting source/index.rst here. Should I update this text in both places?
There was a problem hiding this comment.
Yep, update it in both - the current phrasing presumably dates from when we were still trying to disambiguate distribution packages from import packages by introducing a different term rather than just qualifying "package" as needed.
source/contribute.rst
Outdated
| and tone. Does it sound like something you would say or does it sound like | ||
| you're acting out a part or giving a speech? Feel free to use contractions and | ||
| don't worry about sticking to fussy grammar rules. You are hereby granted | ||
| permission to end a sentence in a preposition. |
There was a problem hiding this comment.
I tried to figure out how to rephrase this sentence so it ended in a preposition, but no such luck :)
There was a problem hiding this comment.
"You are hereby granted permission to end a sentence in a preposition, if that's what you want to end it with." :-) Sorry, couldn't resist.
There was a problem hiding this comment.
YES! Seriously, I spent entirely too much time trying to come up with something like that.
source/contribute.rst
Outdated
|
|
||
| **Use a gender-neutral style** | ||
| Often, you'll address the reader directly with *you*, *your* and *yours*. | ||
| Otherwise, user gender-neutral pronouns *they*, *their*, and *theirs* or |
|
And done! Thanks @ddbeck :) |
* adds an initial contributor and style guide * importantly, ends a sentence in a preposition (@pfmoore succeeded where others had failed) * updates the guide's purpose statement to better reflect common terminology
This PR adds a contributing and style guide started on the
developbranch (with a few edits). Based on the discussion with @jonparrott from #301, this is the first step in retiring thedevelopbranch. Some of this doc is based on conventions that I've seen elsewhere in the guide, other bits are aspirational (e.g., headings use different styles in different places, so I tried to aim for easier to explain and maintain). I'm happy to make any changes needed to get this into mergeable state.