classification
Title: Include Misc/ACKS names into the documentation
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: 15437 Superseder:
Assigned To: ezio.melotti Nosy List: chris.jerdonek, docs@python, eric.araujo, ezio.melotti, georg.brandl, jcea, loewis, meador.inge, pitrou, python-dev, rhettinger, serhiy.storchaka, terry.reedy, tshepang
Priority: normal Keywords: easy

Created on 2012-07-24 11:51 by chris.jerdonek, last changed 2012-09-13 23:12 by ezio.melotti. This issue is now closed.

Messages (18)
msg166279 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-24 11:51
This issue is to include the names in Misc/ACKS into the documentation --
in place of the names from Doc/ACKS.txt.  This was mentioned in the
discussion for issue 15437, which is to add the names from Doc/ACKS.txt
into Misc/ACKS.

This issue should be done shortly after issue 15437.  The current issue
can include (1) converting Misc/ACKS into rst format, (2) deleting
DOC/ACKS.txt (after confirming that any changes since issue 15437 are
reflected in Misc/ACKS), and (3) resolving the intros in the two files
with about.rst's surrounding text so that the text makes sense when
included into the main documentation.

Should Guido's note of acknowledgment in Misc/ACKS be included as is?
And should a new "Python Acknowledgments" section be added to the docs,
or is it okay for this more general acknowledgment to be included in the
section called "About these documents"?  If the former, the "About these
documents" section could link to the more general "Python
Acknowledgments" section to reference documentation contributors.
msg166280 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-24 11:58
-1. Misc/ACKS is fine where it is. No need to include it into the docs.
msg166282 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-24 12:10
Martin, just to be sure, this is to be done after issue 15437 (a dependency), and the location of Misc/ACKS will not change.  Have you already read the discussion there?  Éric said that he recalled it was Georg's preference to do this if Doc/ACKS.txt is removed.  (I personally have no opinion.)
msg166320 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-24 19:03
Ok, please rephrase: what do you mean by "inlude ... into ..."? If the place of Misc/ACKS doesn't change, in what way is it being included into something? And which "documentation" is it being included into, if it doesn't change its location?
msg166322 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-07-24 19:21
> Ok, please rephrase: what do you mean by "inlude ... into ..."?

http://docs.python.org/about.html#contributors-to-the-python-documentation
msg166325 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-24 19:29
I see; I'm changing my vote to -0 then. I don't think this list of names should have been included in the documentation in the first place. Since it is, providing the full list of contributors is just as fine.
msg166327 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-24 19:37
The second sense of the word "include" is in the possible implementation.  Éric pointed out in the other issue's thread that this can be achieved by modifying the existing include directive, for example--

--- a/Doc/about.rst
+++ b/Doc/about.rst
@@ -30,7 +30,7 @@
 documentation, or Python itself.
 
 .. including the ACKS file here so that it can be maintained separately
-.. include:: ACKS.txt
+.. include:: ../Misc/ACKS

The details of the surrounding text still need to be worked out though so that it reads right.
msg166329 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-24 19:57
I think Guido's wording should be included literally in the online version. It very much explains what this list really is and how to interpret it. The post scriptum should be converted into a ReST comment, since it is primarily a note to maintainers.
msg166341 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-07-24 23:34
I agree with Martin and don't think the ACKS list should be exposed further than it already is.
msg166344 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-25 00:18
Is that a -0 then, Raymond?

I think either the combined Misc/ACKS list should be included in the docs, or it should be removed entirely.  If what Meador said is true (that people already in Misc/ACKS who contribute documentation should not be added)--

> Doc/ACKS.txt is *only* for acknowledging documentation contributions.  Serhiy is already in Misc/ACKS.  No need to add him to Doc/ACKS.txt.

http://mail.python.org/pipermail/python-dev/2012-July/121093.html

Then it's not clear to me why the current docs list is meaningful and what exactly it represents.  At the least, the description of the list on the page doesn't match the stated practice.
msg166347 - (view) Author: Meador Inge (meador.inge) * (Python committer) Date: 2012-07-25 01:56
What I meant by that was that Serhiy contributed a code change and was already in Misc/ACKS, therefore no ACKS file should have been updated.  I didn't mean to imply that someone can't be in both files.  My impression is that Misc/ACKS is for code contributions and Docs/ACKS.txt is for documentation contributions.
msg166355 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-25 05:58
Okay, thanks for clarifying.  Then I have no strong opinion.

However, if Doc/ACKS.txt is retained, then I think the Dev Guide should mention Doc/ACKS.txt just as it mentions Misc/ACKS:

http://docs.python.org/devguide/patch.html#preparation

And it should include instructions for when to update which files, and the patchcheck script should be suitably modified.  With only ~230 names versus Misc/ACKS's ~1160 , I'm surprised that Doc/ACKS.txt does not have more names -- especially given that it's not uncommon for documentation changes to accompany code changes (or so one might think).
msg166358 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-25 06:39
I don't know how Doc ACKS is maintained, but I think the devguide is fine as it stands, whether or not Doc ACKS is preserved or not. People should put themselves into Misc/ACKS if they made a contribution, period.

If people need to be acknowledged separately for contributing to the documentation, I think only major contributions (such as writing the documentation for a yet-undocumented module) should be explicitly acknowledged.

I think this all started from the documentation having initially Guido van Rossum given as its sole author, and then later Fred Drake. So Doc/ACKS.txt may have been an attempt to correct the impression that these two are the authors, but I think it went into the wrong direction (eventually leading to the creation of issues such as this one)
msg166409 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-07-25 16:29
FWIW including Misc/ACKS in the doc will probably break the generation of the pdf version of the doc, since it contains non-latin1 characters (see msg166408).  I don't think it's necessary to include the names in the doc.

> I don't know how Doc ACKS is maintained, but I think the devguide is
> fine as it stands, whether or not Doc ACKS is preserved or not. 
> People should put themselves into Misc/ACKS if they made a 
> contribution, period.

In my experience Doc/ACKS.txt is mostly ignored/unmaintained.  I did a lot of work on the docs and my name is not in there, and I don't think I ever added anyone there.

> If people need to be acknowledged separately for contributing to the
> documentation, I think only major contributions (such as writing the 
> documentation for a yet-undocumented module) should be explicitly 
> acknowledged.

It's already possible to give credit directly in the docs using directives like "sectionauthor".
msg166410 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-07-25 16:37
OK, I propose to completely drop the Doc/ACKS.txt from the documentation, and replace it with the words

"Many people have contributed to the Python language, the Python standard library, and the Python documentation. See Misc/ACKS in the Python source distribution for a partial list of contributors"
msg166597 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2012-07-27 18:51
> OK, I propose to completely drop the Doc/ACKS.txt from the documentation, and replace it with the words

Sounds good to me.
msg166606 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-07-27 21:07
I agree with Martin also. A short paragraph and link to the (combined) online file is quite sufficient. There is no need for the file to be in offline copies. And I would make the change in all current versions.
msg170463 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-09-13 22:59
New changeset 48185b0f7b8a by Ezio Melotti in branch '3.2':
#15437, #15439: merge Doc/ACKS.txt with Misc/ACKS and modify Doc/about.rst accordingly.
http://hg.python.org/cpython/rev/48185b0f7b8a

New changeset 2b4a89f82485 by Ezio Melotti in branch 'default':
#15437, #15439: merge with 3.2.
http://hg.python.org/cpython/rev/2b4a89f82485

New changeset 76dd082d332e by Ezio Melotti in branch '2.7':
#15437, #15439: merge Doc/ACKS.txt with Misc/ACKS and modify Doc/about.rst accordingly.
http://hg.python.org/cpython/rev/76dd082d332e
History
Date User Action Args
2012-09-13 23:12:14ezio.melottisetstatus: open -> closed
versions: + Python 2.7, Python 3.2, Python 3.3
resolution: fixed
assignee: docs@python -> ezio.melotti
type: enhancement
stage: needs patch -> resolved
2012-09-13 22:59:31python-devsetnosy: + python-dev
messages: + msg170463
2012-07-27 21:07:58terry.reedysetnosy: + terry.reedy
messages: + msg166606
2012-07-27 18:51:24pitrousetmessages: + msg166597
2012-07-27 18:50:28tshepangsetnosy: + tshepang
2012-07-25 16:37:21loewissetmessages: + msg166410
2012-07-25 16:29:38ezio.melottisetmessages: + msg166409
2012-07-25 06:39:41loewissetmessages: + msg166358
2012-07-25 05:58:18chris.jerdoneksetmessages: + msg166355
2012-07-25 01:56:16meador.ingesetnosy: + meador.inge
messages: + msg166347
2012-07-25 00:18:38chris.jerdoneksetmessages: + msg166344
2012-07-24 23:34:51rhettingersetnosy: + rhettinger
messages: + msg166341
2012-07-24 19:57:18loewissetmessages: + msg166329
2012-07-24 19:37:26chris.jerdoneksetmessages: + msg166327
2012-07-24 19:29:09loewissetmessages: + msg166325
2012-07-24 19:21:11serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg166322
2012-07-24 19:03:35loewissetmessages: + msg166320
2012-07-24 12:10:35chris.jerdoneksetmessages: + msg166282
2012-07-24 11:58:24loewissetnosy: + loewis
messages: + msg166280
2012-07-24 11:53:26chris.jerdoneksetdependencies: + Merge Doc/ACKS.txt names into Misc/ACKS
2012-07-24 11:51:39chris.jerdonekcreate