Initial Motivations & Affiliations page has been merged
Based on the thread a few weeks ago and the subsequent issue tracker discussion at http://bugs.python.org/issue25194, I just committed an initial version of a "Motivations & Affiliations" page in the developer guide.
When the site next updates, that should appear at https://docs.python.org/devguide/motivations.html (it's the last section in the main TOC, with the link appearing right at the bottom of the main page).
In the meantime, the diff can be seen at https://hg.python.org/devguide/rev/0f0ff7d19cfc
The first important section for core contributors is the "Limitations on Scope": https://hg.python.org/devguide/rev/0f0ff7d19cfc#l3.31
That section spells out:
- this is optional, so only fill it in if you think it's in your personal best interests to do so
- for those of us working for commercial redistributors and PSF Sponsor Members, there's a financial transparency consideration, so we should be inclined towards filling out an entry
- folks that are available for consulting or contract work are likely to want to fill it out as a possible source of client lead generation (either directly or via the PSF)
The second important section is the initial guidelines for filling out entries, which are written in a ReST comment: https://hg.python.org/devguide/rev/0f0ff7d19cfc#l3.77
It's hard to judge how well that initial set of guidelines is going to work with just the one entry, so I expect they may need to be revised as more people start adding their own entries. However, I figured it would be better to put the page live and have that discussion here as people start filling it out, rather than speculating further on the issue tracker.
Regards, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 11 October 2015 at 22:33, Nick Coghlan <ncoghlan@gmail.com> wrote:
Based on the thread a few weeks ago and the subsequent issue tracker discussion at http://bugs.python.org/issue25194, I just committed an initial version of a "Motivations & Affiliations" page in the developer guide.
When the site next updates, that should appear at https://docs.python.org/devguide/motivations.html (it's the last section in the main TOC, with the link appearing right at the bottom of the main page).
It's been pointed out that despite the excellent feedback I received from folks on the issue tracker, I still missed a few aspects of the translation away from the legalistic bureaucratese I used in my initial draft (see https://bugs.python.org/file40527/register-of-interests.diff ).
I'll do another pass on that, swapping out the more formal terms (e.g. "disclose") for more common plain English equivalents (e.g. "publish"). If there are other particular phrases and words that seem out of place, please let me know, either directly or here in the thread, as I sometimes lose track of what counts as normal English and what's specifically corporate/institutional English :)
Regards, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On Mon, Oct 12, 2015 at 01:08:27PM +1000, Nick Coghlan wrote: [...]
I'll do another pass on that, swapping out the more formal terms (e.g. "disclose") for more common plain English equivalents (e.g. "publish"). If there are other particular phrases and words that seem out of place, please let me know, either directly or here in the thread, as I sometimes lose track of what counts as normal English and what's specifically corporate/institutional English :)
"Disclose" and "publish" are not synonyms, and "disclose" is common, plain English, not jargon or specifically corporate English. It's found in poetry!
If I disclose my passion,
Our friendship's an end.
--Addison, quoted in Webster's Dictionary (1913)More importantly, it is a standard English idiom. For example, "disclose any conflicts of interest" is a clear sentence and a standard idiom, not jargon, not formal English, but precise. If you replace it with a word like "publish", you introduce uncertainty and reduce clarity. It's not clear what you mean by publish. Is a note in the personals section of the local newspaper good enough, or do I have to take out a full page advertisment in an international magazine?
-- Steve
On 12 October 2015 at 13:08, Nick Coghlan <ncoghlan@gmail.com> wrote:
On 11 October 2015 at 22:33, Nick Coghlan <ncoghlan@gmail.com> wrote:
Based on the thread a few weeks ago and the subsequent issue tracker discussion at http://bugs.python.org/issue25194, I just committed an initial version of a "Motivations & Affiliations" page in the developer guide.
When the site next updates, that should appear at https://docs.python.org/devguide/motivations.html (it's the last section in the main TOC, with the link appearing right at the bottom of the main page).
It's been pointed out that despite the excellent feedback I received from folks on the issue tracker, I still missed a few aspects of the translation away from the legalistic bureaucratese I used in my initial draft (see https://bugs.python.org/file40527/register-of-interests.diff ).
I'll do another pass on that, swapping out the more formal terms (e.g. "disclose") for more common plain English equivalents (e.g. "publish"). If there are other particular phrases and words that seem out of place, please let me know, either directly or here in the thread, as I sometimes lose track of what counts as normal English and what's specifically corporate/institutional English :)
Further off-list feedback: this initial version of the page doesn't do a good job of explaining what the *point* of the page is. While that did get covered in the original python-committers thread and the issue tracker discussion, and is also covered to some degree in the instructions-for-developers in the page source, that doesn't help folks *reading* the page.
I've noted that as a pending update in https://bugs.python.org/issue25194
Regards, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
participants (2)
-
Nick Coghlan -
Steven D'Aprano