Documentation suggestions

[A.M. Kuchling]

Just because that audience is small doesn't mean they are unimportant.
There are currently four actively maintained/developed implementations of
Python. A common language reference manual is important for them, and
indirectly for the people who use the four implementations.

They're not unimportant, but I don't think the reference manual *is*
important to them because they've gotten this far with an outdated
one; the code may be resource enough. This is why I think that the
effort expended to update a document aimed at them might be better
spent on something more widely useful.

I remembered another problem from the weekend with documenting
new-style classes. It seemed reasonable to begin with PEP 252, and
see if any bits of the PEP can be migrated into the RefGuide, but then
I found this comment in the abstract:

[Editor's note: the ideas described in this PEP have been
incorporated into Python. The PEP no longer accurately
describes the implementation.]

So now we're *really* stuck. The RefGuide doesn't describe the rules;
the PEP no longer describes them either; and probably only Guido can
write the new text for the RefGuide. (Or are the semantics the same
and only some trivial details are different?)

--amk

 

[Aahz]

So now we're *really* stuck. The RefGuide doesn't describe the rules;
the PEP no longer describes them either; and probably only Guido can
write the new text for the RefGuide. (Or are the semantics the same
and only some trivial details are different?)

Raymond Hettinger (and/or maybe one of the metaclass wizards) can
probably also write it, with Guido editing after. That might produce
even more accuracy in the end.

 

[rurpy]

IMO the only people who are going to appreciate BNF used for
explanation are those working on language implementations, and they'll
need to understand the Grammar file anyway. The rest of us need a
simpler explanation involving examples.

Having a large and detailed language specification, although an
admirable ideal, is a waste of time when the target audience is
perhaps a few dozen people. Make it useful for everybody and it'll be
worth maintaining.

A language reference manual and a language specification
are two different things, and the existence of bnf/grammar info
in a language reference manual need to turn it into some
inpenaterable ISO-spec like document.

I know that I sometimes want to know if some unusual syntax
is legal or not, particularly when learning a language. The
bnf/grammar stuff is relatively small and if sections are
organised consistently, easily skipped over by readers with
no interest it it.

 

[rurpy]

Iain> I like the Global Module Index in general - it allows quick access
Iain> to exactly what I want. I would like a minor change to it though
Iain> - stop words starting with a given letter rolling over to another
Iain> column (for example, os.path is at the foot of one column, while
Iain> ossaudiodev is at the head of the next), and provide links to each
Iain> initial letter at the top of the page.

I know it's not what you asked for, but give

http://staging.musi-cal.com/modindex/

a try. See if by dynamically migrating the most frequently requested
modules to the front of the section it becomes more manageable.

I think this is pretty cool. But...

Is this only for the online docs? Would documentaion shipped with
Python exclude this, or have a frozen version of it?

My experience with other machine systems that try to guess what
I will want, is they usually get it wrong, and become more of a burdon
than a help.

Often what I like best is consistency. I think I'd find it irritating
if
I got used to clicking on one of the frequently used links, and then
discovered it had been bumped. Even it's changing position might
be irritating.

 

[skip]

rurpy> Is this only for the online docs?

Yes. I don't see that it would be helpful for static docs. Presumably they
will get reorganized. I want something for the many times I return to the
global module index looking for help with a particular module.

rurpy> My experience with other machine systems that try to guess what I
rurpy> will want, is they usually get it wrong, and become more of a
rurpy> burdon than a help.

This isn't guessing. It's more like voting (or like rating systems such as
the Internet Movie Database).

S

 

[Steven Bethard]

Raymond Hettinger (and/or maybe one of the metaclass wizards) can
probably also write it, with Guido editing after. That might produce
even more accuracy in the end.

I'm not a metaclass wizard, but I have submitted a few doc patches
trying to address some of the inaccuracies in the description of
new-style classes and related matters:
http://www.python.org/sf/1123716
http://www.python.org/sf/1163367
The problem is that they don't seem to get accepted (even when
accompanied by positive comments). And unfortunately, I don't currently
have time to do the 5 reviews for 1 deal offered by some of the
python-dev folks.

STeVe

 

[A.M. Kuchling]

Argh, you made me look at the html again - at least now I know *why* it
is so disgusting. I understand there's a new version coming out soon,
hopefully in html 4 strict or xhtml. I'm sure at that point it'll be
easier to use. I can wait.

A new version of LaTeX2HTML, you mean? Can you provide a pointer?

--amk

 

[A.M. Kuchling]

OK I'll bite. That Beginners Guide page has bugged me for a long time.
It's a wiki page but it is marked as immutable so I can't change it.
Here are some immediate suggestions:

Good suggestions; thanks! I've applied most of them.

- Change the sentence "Read BeginnersGuide/Overview to learn the key
points." to "Read BeginnersGuide/Overview to learn what makes Python
special." Or maybe get rid of it completely - I'm not sure evangelism
belongs on this page.

Yes, it does; fairly often the webmaster alias receives e-mails that
ask "so what is Python?"

--amk

 

[BartlebyScrivener]

Andrew,

The site changes for the new-to-Python person are a big improvement in
terms of the sequence of exposures, but from a marketing perspective,
the first thing they read about Python is still aimed at a programmer.
The bulleted points in BeginnersGuide/Overview are, again, things that
are important to programmers ("Automatic garbage collection frees you
from the hassles of memory management" means nothing to me, even now
after reading a Python book and several tutorials).

I wish there were some sort of sexy exposure to Python before hitting
them with the download. Again you purport to be making a page for
someone who's never programmed before, so almost certainly a Windows
user. And a Windows user is not going to download any program until
he's absolutely sure it won't destabilize his fragile system or infect
it. So nobody new to programming and new to Python is going to download
at the point you present them with that opportunity. Too bad there
isn't something like what Ruby does with the "Try Ruby In Your Browser"
thing, which is a very effective marketing tool (although obviously I
chose Python).

http://tryruby.hobix.com/

The other thing I vividly recall struggling with was: Do I download
this Python.org version for my Windows XP machine, because it's the
official one, or do I use the one from ActiveState because others say
it comes with all sorts of goodies for Windows users? I don't know what
the politics are there, but if I were you I'd take a stand and put it
on the download page to help the new person out, who is uncertain about
what to do.

Ultimately I downloaded ActiveState because I found their site easier
to understand (again speaking as a person relatively new to programming
and absolutely new to Python).

Thanks,

rpd

"I read part of it all the way through."--Samuel Goldwyn

www.dooling.com

 

[Kent Johnson]

Good suggestions; thanks! I've applied most of them.

Thanks, this is a big improvement. Here are a few more ideas:

- change "Next, you need to get the Python interpreter installed on your
computer." to "Next, install the Python interpreter on your computer."
(active voice)

- move and rewrite the "You'll want to select a [WWW] text editor..."
sentence. For a raw beginner, this is not the next step and the page it
links to will not be helpful. Tutorials generally start out at the
interpreter prompt, not writing programs in an editor. Whatever editor
is handy and familiar is probably fine for a first program when the time
comes. Here is a suggested rewrite:

"When you are ready to write your first program you will need a text
editor. To get started you can use any editor you are familiar with such
as NotePad or <insert names of other common editors>. As you gain
experience you may want to use a text editors with features that help
you write Python programs. A comprehensive list is here <link>."

I think I would put this before the paragraph beginning "Once you've
read a tutorial".

- Move the "Need to know how to run Python programs on Windows?"
sentence to the last bullet of the list in the next paragraph and
rewrite it to

"Most tutorials assume you know how to run a program on your computer.
If you are using Windows and need help with this, see <link>."

- Change "Next, you're going to want to read a tutorial" to "Next, read
a tutorial"


With these changes the first links on this page are BG/Overview,
BG/Download and BG/NonProgrammers. The second link on BG/NonProgrammers
is a reasonable tutorial and the first link is pretty obviously one to
skip. So a beginner is guided through the necessary steps with nothing
extra or distracting or overwhelming intervening.

Yes, it does; fairly often the webmaster alias receives e-mails that
ask "so what is Python?"

Direct them to the "What is Python?" link on the front page maybe? ISTM
the material in BG/Overview belongs on the pages linked from "What is
Python?"

Thanks,
Kent

 

[Mike Meyer]

Too bad there
isn't something like what Ruby does with the "Try Ruby In Your Browser"
thing, which is a very effective marketing tool (although obviously I
chose Python).

http://tryruby.hobix.com/

I've seen things like this for other language as well. Doing it in
for Python isn't all that hard.

The question is how do you keep the system that the Python code is
actually running on safe? Ruby may have a real bastion mode, but
Python doesn't.

<mike

 

[Aahz]

I've seen things like this for other language as well. Doing it in
for Python isn't all that hard.

The question is how do you keep the system that the Python code is
actually running on safe? Ruby may have a real bastion mode, but
Python doesn't.

Just run the Python code chrooted.

 

[Trent Mick]

[Mike Meyer wrote]

I've seen things like this for other language as well. Doing it in
for Python isn't all that hard.

The question is how do you keep the system that the Python code is
actually running on safe? Ruby may have a real bastion mode, but
Python doesn't.

Nah, the Try Ruby thing is mostly faking it (I believe) rather than
running an actually Ruby interactive session ("bastion'ed" or not).

Trent

 

[skip]

Mike> The question is how do you keep the system that the Python code is
Mike> actually running on safe? Ruby may have a real bastion mode, but
Mike> Python doesn't.

User Mode Linux? chroot?

Skip

 

[skip]

Trent> Nah, the Try Ruby thing is mostly faking it (I believe) rather
Trent> than running an actually Ruby interactive session ("bastion'ed"
Trent> or not).

I don't think so. I tried typing some stuff at the prompt that it wasn't
asking for, like "x = [1,2,3]" followed by "x * 5" when it was asking me to
type "2 + 6". It evaluated both properly as far as I could tell. OTOH, it
hung when I entered "def fib(n)". Never got to the next prompt. Looking at
the Javascript, it appears to be some sort of Ajaxian thing...

Skip

 

[Terry Hancock]

I've seen things like this for other language as well.
Doing it in for Python isn't all that hard.

The question is how do you keep the system that the Python
code is actually running on safe? Ruby may have a real
bastion mode, but Python doesn't.

Should be able to use Jython and run on the visitor's
machine, shouldn't you?

 

[BartlebyScrivener]

You guys are all wizards from mars. If it's easy to do I can tell you
that it would very seductive to a prospective Pythoner, and you avoid
the problem of making them download before they can try out a tutorial.
Thanks for looking at it.

rd

 

[Trent Mick]

[[email protected] wrote]

Trent> Nah, the Try Ruby thing is mostly faking it (I believe) rather
Trent> than running an actually Ruby interactive session ("bastion'ed"
Trent> or not).

I don't think so. I tried typing some stuff at the prompt that it wasn't
asking for, like "x = [1,2,3]" followed by "x * 5" when it was asking me to
type "2 + 6". It evaluated both properly as far as I could tell.

Yah. My guess at what he is doing (and the way I'd probably do this for
Python) is to compile each statement, only allow certain constructs
(like assigning to a variable, defining literals, basic operator usage,
maybe some control flow statements -- although I didn't get that far)
and then execute those.

OTOH, it
hung when I entered "def fib(n)". Never got to the next prompt.

Punted on continued/multi-line statements maybe?

Looking at
the Javascript, it appears to be some sort of Ajaxian thing...

Yup.


Trent

 

[Mike Meyer]

[[email protected] wrote]

Trent> Nah, the Try Ruby thing is mostly faking it (I believe) rather
Trent> than running an actually Ruby interactive session ("bastion'ed"
Trent> or not).
I don't think so. I tried typing some stuff at the prompt that it wasn't
asking for, like "x = [1,2,3]" followed by "x * 5" when it was asking me to
type "2 + 6". It evaluated both properly as far as I could tell.

Yah. My guess at what he is doing (and the way I'd probably do this for
Python) is to compile each statement, only allow certain constructs
(like assigning to a variable, defining literals, basic operator usage,
maybe some control flow statements -- although I didn't get that far)
and then execute those.

I'm working on puttingn this up for Python. I'm planning on using AJAX
to pass the input string to eval on the server. I.e. - you'll be
limited to expressions, which is what it seems like the Ruby thing is
limited to.

On the other hand, with iterators, generators and list comprehensions,
you can do quite a lot with eval.

If anyone else is contemplating putting up something like this, let me
know so we can avoijd duplicating the effort.

<mike

 

[Paul Rubin]

I'm working on puttingn this up for Python. I'm planning on using AJAX
to pass the input string to eval on the server. I.e. - you'll be
limited to expressions, which is what it seems like the Ruby thing is
limited to.

On the other hand, with iterators, generators and list comprehensions,
you can do quite a lot with eval.

How will you stop the server from getting hosed?