[Pydotorg-redesign] Re: User comments on python.org

[Ian Bicking]

On Monday, October 13, 2003, at 01:07 PM, A.M. Kuchling wrote:
> [CC'ing to pydotorg-redesign, and setting followups there, too.]
>
> On Sat, 11 Oct 2003 19:19:41 -0500,
> 	Ian Bicking <ianb at colorstudy.com> wrote:
>> I don't really know how the Python site is set up now, but could
>> comments be included inline as an SSI?  Like
>
> I don't think SSIs are currently enabled, but it wouldn't be hard to 
> turn
> them on.  However, I have two worries about this:
>
> 1) Fitting the comments into the page design -- a page with a lot of
>    comments would be really, really lengthy.

Sites that have this usually offer versions of the documentation with 
and without comments.

I can imagine three places where comments would become excessive -- the 
documentation has problems, the domain is inherently confusing or large 
(the cgi module turns into a tutorial on CGI), or significant recipes 
are included.

These are all basic Wiki refactoring problems -- editing the original 
documentation (to make it less ambiguous, so the comments aren't 
needed, or otherwise improve it); or creating more documentation 
(perhaps linking to other Wiki pages that go on at length on a topic).

> 2) What if people post obscenities or harmful material?
>    Showing comments by default would be embarrassing; if you have to
>    explicitly choose to view them, this is less worrying.
>    Python.org has a really good Google PageRank, I expect, making it
>    a good target for link spam, so this is something to worry about.

I think it will be better when the comments are included inline, 
because many more people will view the comments.  The same is true for 
general accuracy.  Spam and such is best handled on a Wiki when there's 
lots of people to fix it.  But maybe php.net or other places would have 
more experience on this (php.net does put comments at the end of each 
page).  Maybe user logins are a good way to raising the bar to 
discourage useless (or worse) comments.

I also like the idea of using Wiki pages instead of the traditional 
appended comments -- I think it would be more constructive.

> The Wiki has mostly escaped such vandalism; presumably it's unobtrusive
> enough that spammers haven't noticed it.
>
>> 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
>
> Perhaps.  Wiki names can contain '/', so we can have annotations for 
> every
> single page on the site by just using the full path name.  The 
> question is
> whether we need that level of support; perhaps the docs are the only 
> place
> where comments are valuable.  I do think that comments on the reference
> manual or the Distutils manuals would be useful.  (Possibly PEPs, too?)

There's definitely places besides the library reference that could use 
these comments, but I think they could all be listed out explicitly.  A 
little rewrite magic could keep it in a flat hierarchy.

> I did a bit of experimenting with the separate page, adding JavaScript 
> to
> ht2html's output and adding an ugly 'view comment' link.  If we're
> interested in pursuing this, I'm willing to do the following:
>
> 1) Make a set of experimental pages with comment links, so we can see
>   what they look like and how they work in practice.
> 2) If 1) looks worthwhile, then I'll make a new Wiki for user notes 
> that has
>    minimal styling.
>
> What I'd really need is presentation suggestions: *how* to show the 
> comment
> link?

I think it should *not* be in the sidebar -- the sidebar is 
navigational and it's implied that it's specific to the site or 
section, not that particular page.  But the library reference doesn't 
really have a sidebar, so nevermind that...

In the top bar then, by the TOC/modules/index links... or maybe the 
arrows, since those are context-sensitive, where the other links are 
global.  Then maybe a larger link at the bottom of the page (kind of a 
further reading link).

If the comments aren't included inline, I feel like it would be 
important to indicate if there *were* any comments.  It's annoying and 
discouraging to be in a site that hints at things that aren't there -- 
and there will be a lot of "not there" when this feature is first 
added.  But I think implementing that would be fairly hard to do.  But 
important.  But hard.  Sigh.

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