On Jul 29, 2011, at 08:24 AM, Eli Bendersky wrote: >Alright, I think there's now a sufficiently wide consensus to move the >documentation of Lib/test and Lib/test/support in particular to the >devguide, which raises a question:
I haven't been following this thread, so I caught up on Gmane. I'm somewhat uncomfortable with this decision. I understand why you want to do this, but I still think it might not be the right thing. For better or worse, test.support is part of the standard library, so moving its documentation elsewhere sets a bad precedent to me. Many times I work on Python while completely off-line. If I've had the foresight to build the docs before I go off-line, all the better, but even if not, I have the .rst files to consult. Now I'll have to remember to *also* grab the devguide so that I have the complete documentation of the stdlib. I also think this underestimates how blurry the line is between users and developers. Think about yourself: when did you suddenly graduate from user of Python to developer of Python? I know that I often talk to people who would consider themselves "just" users of Python, but feel comfortable with their occasional spelunking into the Python tree looking for whatever nugget of code or documentation will help them understand their problem. The devguide, as useful and cool as it is, is still immature and hard to discover. I think more time will improve its organization, and it's not even linked to from docs.python.org. So I'm curious, why is this move better than adding noindexes, or just trusting users to understand the difference between test.support.unlink() and os.unlink()? If I currently search for 'unlink', os.unlink comes up first, which is good, and that should be preserved. The presence or not of some test.support.unlink documentation isn't going to make the search results that much better or worse (there's already 14 hits). Cheers, -Barry
signature.asc
Description: PGP signature
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
