[Python-Dev] Documentation reorganization

[Adam Olsen]

On Tue, Mar 4, 2008 at 8:03 PM, Stephen J. Turnbull <stephen at xemacs.org> wrote:
> Adam Olsen writes:
>   > On Tue, Mar 4, 2008 at 3:13 PM, Stephen J. Turnbull <stephen at xemacs.org> wrote:
>
>   > > I would like to see the clear division between the language (ie,
>   > > the syntax) and the built-in functionality maintained.  I'm not
>   > > sure I like the proposed title for that reason.
>   >
>   > 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.
>
>  This is Python; of course practicality beats purity.  I have no
>  problem with putting some keywords in the "built-in functionality"
>  section, or even (boggle) duplicate them across the two sections.

-1 on duplicating anything.  Provide links to a single location
instead.  Otherwise you end up with two explanations of the same
thing, with different wording and subtle differences or missing
details.


>  I too was put off by the separation of syntax from built-in
>  functionality when I first started using the documentation, but later
>  I came to appreciate it.  I'm a relatively casual user of Python, and
>  having a spare "syntax" section has made it much easier to learn new
>  syntax such as comprehensions and generators.  I suspect it will make
>  it a lot easier to learn the differences between Python 2 and Python
>  3, too.  I do not want to lose that.

I learned them through third-party docs.  Even now I have a hard time
finding list comprehension/generator expression in the docs.
Apparently they're in the Expression section, under "Displays for
lists, sets and dictionaries", and neither that nor anything with list
comprehension or generator expression is in the index.  The term
"Displays" is pretty obscure as well, not something I've seen used
besides on this list or right there in the documentation.


>  I don't pretend to be speaking for anyone else, but I'd be surprised
>  if I were unique.<wink>

Your experiences *shouldn't* be unique, but I'm afraid they might be.
Another example is the use of BNF, which although dominant in its
field, it provides a steep learning curve for most programmers.

I'm afraid this has turned into a rant, but it should be seen as the
experiences of someone who relies on the documentation a great deal.
Is there a better way to channel feedback on the documentation?

-- 
Adam Olsen, aka Rhamphoryncus