User comments on python.org

[Ian Bicking]

On Saturday, October 11, 2003, at 10:33 AM, A.M. Kuchling wrote:
> On Fri, 10 Oct 2003 12:58:49 GMT,
> 	Alex Martelli <aleax at aleax.it> wrote:
>> they're referring to the .net rather than the .org site.  
>> "Annotatable"
>> docs (perhaps with some overview) sure sounds like a way-cool idea, 
>> but
>> I have no first-hand experience of how well it works in practice.
>
> Well, let's get some experience.  python.org already has a Wiki, so we 
> have
> a facility for editing text.  It would be straightforward to have a
> "View/Edit comments" link on each page that directed the user to a
> corresponding Wiki page, perhaps popping it up in a separate window.
>
> Questions:
>
> * Including comments in the page is difficult; I looked at modifying
>   MoinMoin to do this, but it's not easy. So how can the link be made 
> fairly
>   obvious?  Links at the bottom of page aren't very obvious.  A 
> sidebar link
>   perhaps?  (Even if we don't do annotation for the current site 
> design, it
>   might be worth coming up with a good indicator for the redesigned 
> version.)

I don't really know how the Python site is set up now, but could 
comments be included inline as an SSI?  Like

<!--#include virtual="/cgi-bin/moinmoin.cgi/pagename" -->

?  Maybe MoinMoin can be set up to use extremely minimal markup (just 
the page content and the barest of controls).  I think it would be best 
done as a separate wiki, maybe with a namespace that fits the library 
documentation structure better.  Or maybe both are possible.  It would 
be neat if it hooked into the normal Wiki, but found (either via some 
markup or just automatically) all references to other modules and 
functions and such.

> * Should comment links be on every single page, or should they just be
>   limited to certain sections, such as /doc/current/?

Maybe even just /doc/current/lib -- I don't imagine comments on indexes 
and such to be that useful.  Well, there's several things under 
/doc/current that would also make sense, but I don't think it would be 
hard to make a complete list.

Some places you might not want to show the comments in the page itself, 
like the tutorial -- I think it could be overwhelming and misleading.  
But if possible, it would be quite advantageous to show comments on the 
same page as most reference documentation.

--
Ian Bicking | ianb at colorstudy.com | http://blog.ianbicking.org