[Python-Dev] Documentation reorganization [was: ... for ability to execute zipfiles & directories]

[Adam Olsen]

On Tue, Mar 4, 2008 at 5:04 PM, Steve Holden <steve at holdenweb.com> wrote:
> Greg Ewing wrote:
>  > Adam Olsen wrote:
>  >> Such a division would make it unnecessarily hard to find documentation
>  >> on True, False, None, etc.  They've become keywords for pragmatic
>  >> purposes (to prevent accidental modification), not because we think
>  >> they ideally should be syntax instead of builtins.
>  >
>  > Maybe the solution is to rename the Library Reference
>  > to the Class and Module Reference or something like
>  > that.
>  >
>  Although DRY is fine as a programming principle, it fails for pedagogic
>  purposes. We should therefore be prepared to repeat the same material in
>  different contexts (hopefully by including some common documentation
>  source rather than laborious and error-prone copy-and-paste).
>
>  Document things where people expect to find them. (Now *there's* a
>  usability study screaming to be done ... and SoC is coming up).

Python's usage of import makes it clear when something is imported
from a library, as opposed to being an integral part of the language.
To me, this is an obvious basis on whether to look in the language
reference or in the stdlib reference.

That said, it would be useful to also have a link for major builtin
types in the stdlib section, if only for people who learned to look
for them there.


-- 
Adam Olsen, aka Rhamphoryncus