[Python-Dev] New Pythondoc by effbot

[Georg Brandl]

Guido van Rossum wrote:

>> > Which (despite having "perma" in its name) evaporates and leaves
>> > behind a link to os.path.html#join.
> 
>> 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.

Exactly what I had in mind. And we can add markers by request of the
c.l.py "support" regulars.

>> 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!

Well, floating the summary is no problem, but it wouldn't stay at the side
if you scroll down then.

I updated the mockup a bit:

http://home.in.tum.de/~brandlg/zipfile.html

An alternative with floating summary:

http://home.in.tum.de/~brandlg/zipfile-float.html

>> >> 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.)

Agreed. Something like a "discussion page" could be fruitful.

>> (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).

+1.

> [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.

+1.

> (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.

That would have to be decided in situ.

regards,
Georg