Re: User comments on python.org

Discussion in 'Python' started by Ian Bicking, Oct 12, 2003.

  1. Ian Bicking

    Ian Bicking Guest

    On Saturday, October 11, 2003, at 10:33 AM, A.M. Kuchling wrote:
    > On Fri, 10 Oct 2003 12:58:49 GMT,
    > Alex Martelli <> 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 | | http://blog.ianbicking.org
    Ian Bicking, Oct 12, 2003
    #1
    1. Advertising

  2. [CC'ing to pydotorg-redesign, and setting followups there, too.]

    On Sat, 11 Oct 2003 19:19:41 -0500,
    Ian Bicking <> 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.

    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.

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

    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?

    --amk
    A.M. Kuchling, Oct 13, 2003
    #2
    1. Advertising

  3. Ian Bicking

    Mike Rovner Guest

    Skip Montanaro wrote:
    > amk> 1) Fitting the comments into the page design -- a page with
    > a lot amk> of comments would be really, really lengthy.
    >
    > I would prefer to see a little icon next to paragraphs with comments.
    > That minimizes the change in length. Click 'em to pop up a window
    > (or something) with the relevant comments.


    Given that we start with wiki comments, I'd prefer to have page coments
    rather than
    paragraph comments. Something like DocumentationComments/ref/imaginary
    for doc/current/ref/imaginary.html with page autocreation feature for new
    comments
    (with just back reference to the doc page and short invitation).

    > amk> 2) What if people post obscenities or harmful material?
    > pages, or at least to the RecentChanges page, so they are alerted
    > quickly to changes. Juergen, Guido and I have all reverted Wiki
    > changes.


    Wiki is being maintained, it's easy to undo changes, sofar this was not a
    problem.

    > I'd be against anything which actually modified the content of a page
    > as a result of adding a comment, if for no other reason than it would
    > have to integrate with ht2html+CVS, at least for the forseeable
    > future.


    I second that. Wiki is too volatile, let's doc maintainer to incorporate
    (valuable) wiki content into the real doc page (and update/remove wiki
    comments ;))

    Mike
    Mike Rovner, Oct 13, 2003
    #3
  4. On Mon, 13 Oct 2003 13:07:25 -0500, "A.M. Kuchling" <> wrote:

    >[CC'ing to pydotorg-redesign, and setting followups there, too.]

    (somehow the email address got into the newsgroup slot for me, so I had to fix it)
    >
    >On Sat, 11 Oct 2003 19:19:41 -0500,
    > Ian Bicking <> 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.
    >
    >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.
    >
    >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?)
    >
    >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?

    Have a look at

    http://www.xml.com/axml/testaxml.htm

    for a way of associating commentary with (it says, at least) unchanged original matter
    (in this case the XML spec). It's pretty easy on the eyes. I don't know the implementation,
    but I think that separation of pristine original from comment material would be good. The
    above site probably has the advantage of heavy xml tagging in the original that the commentary
    database can used for retrieving associated commentary, I would guess.

    Since full comment generation for dynamic javascript-controlled interaction is somewhat
    computer-costly, caching results of generating responses to comments would make sense,
    I think, and I don't think generating it should be the default.

    If the python.org server is able to insert an optional footer chunk just before the </html>
    when so configured to do it for a directory or a file (I don't know if Apache can do that,
    since I just made it up, but ISTM it would be a useful option ;-), then that footer could
    contain a link for viewing commentary.

    The link would go to a comment-server URL, e.g., commentary.python.org/coments.cgi,
    The cgi program will see HTTP_REFERER from the page the user clicked the comments link on,
    and it can either get a copy via HTTP, or look it up on the local hard disk if it's local.

    The URL can also be used as a key into a database of commentary, where also commenter-accounts
    could be maintained to keep out spammers.

    With the original page plus a database of commentary, the problem becomes building a new
    image of the original with unobtrusive commentary navigation. With javascript you could
    do floating hint text from commentary title lines associated with paragraphs or other
    elements you were mousing over. Clicking might put the commentary in a separate popup window.
    Right clicking on a previous comment might mean pop a form to add your 2 cents. Right
    clicking on the main page where no comment hint is being displayed would pop up the
    same but with an option to give it a title, since it's new commentary.

    All of this is pretty much paragraph oriented. Indexing locations, which have to be w.r.t.
    unmarked text in the original can do some kind of soft hash of <p> sections in the original
    as indices instead of using line numbers, so the data base can have the hashes as keys, and
    not get thrown too much by updates in the original. Actual anchor targets and tag ids
    can be used too I suppose (I'm just thinking out loud ;-) Anyway, you get the idea. If it
    makes you rich, I want a piece ;-)

    my 2 cents ;-)

    Regards,
    Bengt Richter
    Bengt Richter, Oct 14, 2003
    #4
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Replies:
    0
    Views:
    316
  2. Replies:
    0
    Views:
    312
  3. Replies:
    0
    Views:
    312
  4. PerlFAQ Server
    Replies:
    0
    Views:
    677
    PerlFAQ Server
    Feb 3, 2011
  5. PerlFAQ Server
    Replies:
    0
    Views:
    681
    PerlFAQ Server
    Apr 4, 2011
Loading...

Share This Page