(original) (raw)
>Alright, I think there's now a sufficiently wide consensus to move theI haven't been following this thread, so I caught up on Gmane.
>documentation of Lib/test and Lib/test/support in particular to the
>devguide, which raises a question:
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
Why is it part of stdlib though? Isn't the stdlib something that's exposed to all Python programmers? How should an ordinary programmer (not a core dev) know some parts of stdlib are out of limits, if they are even documented and appear in the index - should he read the note at the top of the documentation page? Imagine a desperate programmer behind schedule who is looking for some particular functionality in stdlib and finds it in test.support - will he not use it and later complain we don't keep backwards-compatibility. Sure, he's at fault, but I think we can make such cases much rarer by making the distinction between user-exposed modules and core-dev-exposed modules more explicit.
�
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 think this is because you're experienced and probably know all the contents of the devguide anyway. Junior core-devs need the devguide handy for other reasons as well.
�
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.
Isn't this what we're trying to prevent, though? One should never even have to look at test.support unless he's working *on Python*.
�
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.
Maybe this is the main point here - what makes it immature? What makes it hard to discover? Maybe these issues can be fixed.
�
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).
I think the unlink&rmtree functions are just a symptom. The real issue here is - what is the devguide for, and how is it different from Python's existing documentation? What should go into the official docs, and what should go into the devguide? Once we agree on these question, I think the test.support dilemma will solve itself.
Eli