[Python-Dev] New Pythondoc by effbot (original) (raw)

Guido van Rossum guido at python.org
Sun Jan 22 17:16:30 CET 2006

(This is a bulk reply to several messages in this thread from Georg and Fredrik.)

[Georg]

>> http://effbot.org/lib/os.path.join

[Guido]

> Which (despite having "perma" in its name) evaporates and leaves > behind a link to os.path.html#join.

[Georg]

There may be other uses (e.g. marking a certain location in the docs with a "permalink" marker so that one can point the user to /lib/marker. Especially useful for the tutorial and recurring c.l.py questions ;)

Rather than allowing users to add new markers I'd like the document to be sprinked generously with pregenerated markers to which one can easily linked. I've seen sample docs (not for Python) with such a feature.

[Fredrik, in a different message]

"permalink" was george's term; I'm just calling them "link URLs"

http://online.effbot.org/20060101archive.htm#link-doc to make them "real permalinks", we could: - generate individual pages for all targets (on demand), with a "see this in context" - return the same page and use some javascript trickery to emulate anchors or use some other approach that I cannot think of right now

That sounds overkill. But if you could drop the redundant ".html", the links in the source could look like like

.../os.path#join

which is just fine with me (and solves the problem of what part is the module, on which you spend altogether much time explaining how to compute in the current version :-).

however, at this point, I'm more interested in getting the information model to a point where this can be done.

Understood. What's still missing from the info model? It looks pretty complete to me from a quick scan.

[Georg again]

>> What I would suggest (for any new doc system) is a "split" view: on the left, >> the normal text, on the right, an area with only the headings, functions, >> example and "see also" links (which preferably stays in sight). This way, you >> always keep the outline in view.

[Guido]

> Can you mock that up a bit? I'm somewhat confused about what you're > requesting, and also worried that it would take up too much horizontal > space. (Despite that monitors are wider than tall, horizontal real > estate feels more scarce than vertical, because horizontal scrolling > is such a pain.)

[Georg]

Something like

http://home.in.tum.de/~brandlg/zipfile.html (It works this way (position: fixed) in most browsers, for IE one would have to apply compatibility hacks.)

I believe there's a CSS trick (most often used for images) that can makes the summary window "float" to the right so that below it the main text resumes the full breadth of the window. If you can pull that off I think this is a good addition!

>> Of course, I wouldn't say no to a user-commenting system, but this would have to >> be moderated. > > Why? If wikipedia can do without moderation (for most pages) then why > couldn't the Python docs?

Well, why not... it's surely worth a try. Perhaps using a spam filter like most modern weblogs would suffice.

Have you studied wikipedia's approach? It's multi-layered and worth learning from (start with their FAQ on editing).

(And by the way, I am not advocating writing the docs as one big wikipedia -- only the user commentary.)

[Fredrik again]

the [] syntax has its issues, including that it makes keyword arguments look like positional arguments,

(I think that is actually Python's fault for not distinguishing them in the function definition. :-)

and that descriptions that have lots of optional arguments tend to look like either

foo([a[,b[,c[,d[,e[,f]]]]]]) foo([a][,b][,c][,d][,e][,f]) where the first one is ugly and hard to read, and the latter is, strictly speaking, not correct.

Or (my favorite, but still wrong)

foo([a, b, c, d, e, f])

there are ways to address all these problems with a more pythonic syntax, but I'll have to get back to that later.

Please do.

[Fredrik, in yet another message]

anyway, what I intended to say was that we should work harder on lowering the threshold for drive-by contributions; it should be possible for anyone to notice a problem, add a comment or correction, preview the correction properly rendered, and submit it to a moderation queue, in less than a minute.

Given that it will take significantly longer to process the queue I don't necessarily want to make the contribution process too easy -- we need to balance the quality of the contributions with the ease to make them. For many simple corrections (spelling, grammar, inversions, some factual mistakes) the need to preview the correction properly rendered is quite unnecessary; the important part is being able to point at any word or words in the text and attach a comment.

(I still think moderation is needed before corrections are made visible, but that should be no harder, nor require any more tools, than making the correction in the first place. I'm sure we could get some turbogears/django hackers to build us a nice moderation queue webapp in no time at all...)

Agreed. But as I said above, I think there should also be a way to simply add comments, without moderation (but with wikipedia-style editing / spam-removal / moderation after-the-fact). And, probably, if we don't get to the moderation queue etc., the comments wiki could serve as a moderation queue as well. Being public, it would also reduce the submission of duplicate corrections (especially when the moderator is out of town for a while).

[Fredrik, later]

if we move over to a web-oriented (wiki-ish) maintenance model, we probably have to accept that "X" will, sometimes, be a future release.

This makes me worry that you're thinking of abandoning having separate docs per version. That would be a shame; I think the docs ought to be maintained well enough to be authorative for a particular version (modulo bugs in the docs). Perhaps we could add links that let you navigate between versions quickly, and hopefully we can somehow (optionally?) merge the wiki-style user comments across versions. (Although I can also see the point of starting afresh for each release -- at some point the sheer amount of (possibly outdated) user comments reduces their usefulness.

-- --Guido van Rossum (home page: http://www.python.org/~guido/)

More information about the Python-Dev mailing list