[Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation

Steven D'Aprano steve at pearwood.info
Sun Nov 28 01:43:48 CET 2010


Georg Brandl wrote:
> Hi,
> 
> at <http://dpo.gbrandl.de/contents>, you can look at a version of the 3.2
> docs that has the upcoming commenting feature.  JavaScript is mandatory.
> I've switched on anonymous comments for testing, but usually at least
> comments from anonymous users can be moderated.  Be sure to test the
> "propose a change" feature too.  Login currently allows OpenID exclusively.

Testing as an anonymous user with Konqueror 3.5.9
=================================================

I can show comments, and add them, but I can't hide them once shown.

Once I add a comment, the UI for adding a comment (text field and Add A 
Comment button) disappears.

"Propose a change" doesn't work for me *at all* -- it just scrolls to 
the top of the page.

Likewise for the "sort by" links, the "markup" links and the Vote Up and 
Vote Down buttons.

There are no "Reply" and "Proposal" controls visible.


Testing with Epiphany ("Gnome Web Browser") 2.18.3
==================================================

The text field and Add A Comment button also disappear after adding a 
comment. Hiding the comment block and re-showing it makes it return.

The sort by and markup links seem to work. The threading model is 
unintuitive and strange -- if I reply to a comment, the reply doesn't 
show up anywhere near the comment I replied to.

I would suggest that proposals should be visible by default.

The algorithm used to highlight changes in proposals is 
counter-intuitive. For example, I proposed a change to this text:

     factorial.  Raises :exc:`ValueError` if *x* is not integral
     or is negative.

by inserting the word "interestingly" before "integral":

     factorial.  Raises :exc:`ValueError` if *x* is not
     interestingly integral or is negative.

This was highlighted as:

     factorial.  Raises :exc:`ValueError` if *x* is not
     inteRESTINGLY INTEgral or is negative.

instead of the more intuitive:

     factorial.  Raises :exc:`ValueError` if *x* is not
     INTERESTINGLY integral or is negative.



Performance really is poor :( There is a noticeable lag on even hiding 
and showing the smallest thing.


-- 
Steven



More information about the Doc-SIG mailing list