FAQ
Georg> at <http://dpo.gbrandl.de/contents>, you can look at a version of
Georg> the 3.2 docs that has the upcoming commenting feature.

Very cool.

Georg> Any feedback is appreciated (I'd suggest mailing it to doc-SIG
Georg> only, to avoid cluttering up python-dev).

It would be nice if you could "invert" things and show comments with links
back to the pages/blocks where those comments were made. That would seem to
be useful for a documenter who wants to know where all the comments are.
Unless you have some hidden interface it seems like you just have to
navigate to every page and look for bubbles.

Skip

Search Discussions

  • Georg Brandl at Nov 25, 2010 at 7:30 am

    Am 24.11.2010 22:23, schrieb skip at pobox.com:
    Georg> at <http://dpo.gbrandl.de/contents>, you can look at a version of
    Georg> the 3.2 docs that has the upcoming commenting feature.

    Very cool. Thanks!
    Georg> Any feedback is appreciated (I'd suggest mailing it to doc-SIG
    Georg> only, to avoid cluttering up python-dev).

    It would be nice if you could "invert" things and show comments with links
    back to the pages/blocks where those comments were made. That would seem to
    be useful for a documenter who wants to know where all the comments are.
    Unless you have some hidden interface it seems like you just have to
    navigate to every page and look for bubbles.
    Yes, that's definitely one thing I had in mind for the moderator side. I'm
    leaning toward the "don't keep comments endlessly, but fold back good
    suggestions into the main text" side of things, so a good view of "things
    to do" is definitely needed.

    Georg
  • Brian Curtin at Nov 26, 2010 at 3:33 pm

    On Wed, Nov 24, 2010 at 14:24, 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.

    Credits go to Jacob Mason, whose GSOC project is responsible for almost all
    of what you see there. [1]

    Please test on a smaller page, such as <http://dpo.gbrandl.de/library/math
    ,
    there is currently a speed issue with larger pages. (Helpful tips from
    JS experts are welcome.)

    Other things I have to do before this can go live:

    * reuse existing logins from either wiki or tracker?
    I would vote for reuse of the tracker login. That way, if a user proposes a
    change, an issue could be generated from their tracker ID, they'll be nosy,
    have follow-up input, etc. This way people get a better sense of how their
    contribution flows along and they'll be included throughout the process.

    (sorry if I'm repeating anything -- I'm not subscribed to doc-sig)
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20101126/412cf4ba/attachment.html>
  • Average at Nov 26, 2010 at 8:52 pm

    On Wed, Nov 24, 2010 at 1:24 PM, Georg Brandl wrote:

    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.
    Credits go to Jacob Mason, whose GSOC project is responsible for almost all
    of what you see there. [1]

    Nice job.
    Other things I have to do before this can go live:
    * reuse existing logins from either wiki or tracker?
    +1, Anonymous comments good too...

    mark
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20101126/9e881ee5/attachment.html>
  • Fred Drake at Nov 26, 2010 at 9:28 pm

    On Fri, Nov 26, 2010 at 3:52 PM, average wrote:
    Anonymous comments good too...
    I suspect anonymous comments fall into the same category as anonymous
    issue tracker submissions. We've disallowed those for good reasons,
    and those make sense in this case as well.

    For the moderator side of things, I wonder if it makes sense to
    actually create a tracker issue behind the scenes for each comment;
    that would take care of the discovery issue for maintainers.


    ? -Fred

    --
    Fred L. Drake, Jr.? ? <fdrake at acm.org>
    "A storm broke loose in my mind."? --Albert Einstein
  • Nick Coghlan at Nov 27, 2010 at 11:24 am

    On Sat, Nov 27, 2010 at 7:28 AM, Fred Drake wrote:
    On Fri, Nov 26, 2010 at 3:52 PM, average wrote:
    Anonymous comments good too...
    I suspect anonymous comments fall into the same category as anonymous
    issue tracker submissions. ?We've disallowed those for good reasons,
    and those make sense in this case as well.
    Are you sure about that?

    The problem with general tracker submissions is that we almost always
    need additional information from the original submitter (what version,
    what platform, does it work if you try version X+1, etc). Opening up
    anonymous submissions would just mean more work for tracker folks in
    trying to reproduce the problems, failing and then closing them as
    "works for me" or "not enough information". None of those reasons
    apply to doc comments - "this is wrong", "this is unclear and would be
    better worded as 'make sure to do X before doing Y'" are potentially
    useful even if the docs editors never hear from the submitter ever
    again. The key difference is that the doc maintainers don't need to
    try to reproduce anything - they just read the comment, decide whether
    or not they agree with it and then either apply it, modify and then
    apply it, or else deep-six it, never to be seen again.

    Cheers,
    Nick.

    --
    Nick Coghlan?? |?? ncoghlan at gmail.com?? |?? Brisbane, Australia
  • Georg Brandl at Nov 27, 2010 at 8:47 pm

    Am 27.11.2010 12:24, schrieb Nick Coghlan:
    On Sat, Nov 27, 2010 at 7:28 AM, Fred Drake wrote:
    On Fri, Nov 26, 2010 at 3:52 PM, average wrote:
    Anonymous comments good too...
    I suspect anonymous comments fall into the same category as anonymous
    issue tracker submissions. We've disallowed those for good reasons,
    and those make sense in this case as well.
    Are you sure about that?

    The problem with general tracker submissions is that we almost always
    need additional information from the original submitter (what version,
    what platform, does it work if you try version X+1, etc). Opening up
    anonymous submissions would just mean more work for tracker folks in
    trying to reproduce the problems, failing and then closing them as
    "works for me" or "not enough information". None of those reasons
    apply to doc comments - "this is wrong", "this is unclear and would be
    better worded as 'make sure to do X before doing Y'" are potentially
    useful even if the docs editors never hear from the submitter ever
    again. The key difference is that the doc maintainers don't need to
    try to reproduce anything - they just read the comment, decide whether
    or not they agree with it and then either apply it, modify and then
    apply it, or else deep-six it, never to be seen again.
    I agree. I'd rather put in aggressive spam-filtering than block anonymous
    comments; this commenting really is about easy and quick feedback rather
    than an involved process.

    That said, it really depends on how people are using the comment feature
    once it's in place. If we see too many unqualified or nonsense comments
    from anonymous users, we can still decide to block them.

    Georg
  • Fred Drake at Nov 28, 2010 at 4:09 am

    On Sat, Nov 27, 2010 at 6:24 AM, Nick Coghlan <ncoghlan at gmail.com> wrote in response to my comment about anonymous comments:
    Are you sure about that?
    I'm quite certain. Experience will tell whether I'm right, of course.
    The problem with general tracker submissions is that we almost always
    need additional information from the original submitter (what version,
    what platform, does it work if you try version X+1, etc). Opening up
    anonymous submissions would just mean more work for tracker folks in
    trying to reproduce the problems, failing and then closing them as
    "works for me" or "not enough information". Right.
    None of those reasons
    apply to doc comments - "this is wrong", "this is unclear and would be
    better worded as 'make sure to do X before doing Y'" are potentially
    useful even if the docs editors never hear from the submitter ever
    again.
    Bug reports are also *potentially* useful even without further
    information from the OP. It may well contain enough information.

    Doc comments saying "this is unclear" or "this is wrong" can easily
    trigger a request for clarification: "What more did you want to know?"
    "Why do you think this is incorrect?"
    The key difference is that the doc maintainers don't need to
    try to reproduce anything - they just read the comment, decide whether
    or not they agree with it and then either apply it, modify and then
    apply it, or else deep-six it, never to be seen again.
    A comment that says the doc is wrong may well trigger an attempt to
    use the API in question, and confusion because the comment didn't
    include enough information to identify the specific can the OP is
    really talking about.


    ? -Fred

    --
    Fred L. Drake, Jr.? ? <fdrake at acm.org>
    "A storm broke loose in my mind."? --Albert Einstein
  • Nick Coghlan at Nov 27, 2010 at 12:05 pm

    On Thu, Nov 25, 2010 at 6:24 AM, 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.
    Very nice!

    I'm not sure what to do about the discoverability of the comment
    bubbles as the end of each paragraph. I initially thought commenting
    wasn't available on What's New or the Using Python docs until seeing
    where the blue comment bubbles appeared in the math module docs.

    A discreet notice at the bottom of the sidebar and/or an explanation
    at the "Report a Bug" page may cover it I guess.
    Please test on a smaller page, such as <http://dpo.gbrandl.de/library/math>,
    there is currently a speed issue with larger pages. ?(Helpful tips from
    JS experts are welcome.)
    I gave the JS a fair few comments on the first paragraph to digest. I
    also put my detailed UI comments there as well (I needed something to
    write about while testing, so I figured I may as well make it useful
    to you!)
    Other things I have to do before this can go live:

    * reuse existing logins from either wiki or tracker?
    Tracker sounds like the best bet to me.
    Any feedback is appreciated (I'd suggest mailing it to doc-SIG only, to avoid
    cluttering up python-dev).
    My comments may on the math module may give you a chance to see how
    easy it is to get text out of comments into a form suitable for
    sending to a mailing list or posting to a tracker issue for further
    discussion :)

    Cheers,
    Nick.

    --
    Nick Coghlan?? |?? ncoghlan at gmail.com?? |?? Brisbane, Australia
  • Georg Brandl at Nov 27, 2010 at 8:45 pm

    Am 27.11.2010 13:05, schrieb Nick Coghlan:
    On Thu, Nov 25, 2010 at 6:24 AM, 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.
    Very nice!

    I'm not sure what to do about the discoverability of the comment
    bubbles as the end of each paragraph. I initially thought commenting
    wasn't available on What's New or the Using Python docs until seeing
    where the blue comment bubbles appeared in the math module docs.

    A discreet notice at the bottom of the sidebar and/or an explanation
    at the "Report a Bug" page may cover it I guess.
    Yeah. I'd rather keep links for uncommented paragraphs hidden by default
    though; the cluttering is greatly reduced that way.

    One thing we need to decide is whether to keep the icons at all; maybe a
    text link (see http://book.realworldhaskell.org/read/ for an example)
    is more obvious.
    Please test on a smaller page, such as <http://dpo.gbrandl.de/library/math>,
    there is currently a speed issue with larger pages. (Helpful tips from
    JS experts are welcome.)
    I gave the JS a fair few comments on the first paragraph to digest. I
    also put my detailed UI comments there as well (I needed something to
    write about while testing, so I figured I may as well make it useful
    to you!)
    Thanks! :)
    Other things I have to do before this can go live:

    * reuse existing logins from either wiki or tracker?
    Tracker sounds like the best bet to me.
    I'll confer with Martin on this one then.

    Georg
  • Steven D'Aprano at Nov 27, 2010 at 10:11 pm

    Nick Coghlan wrote:
    On Thu, Nov 25, 2010 at 6:24 AM, 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.
    Very nice!

    I'm not sure what to do about the discoverability of the comment
    bubbles as the end of each paragraph. I initially thought commenting
    wasn't available on What's New or the Using Python docs until seeing
    where the blue comment bubbles appeared in the math module docs.
    I wonder what the point of the comment bubbles is? This isn't a
    graphical UI where (contrary to popular opinion) a picture is *not*
    worth a thousand words, but may require a help-bubble to explain. This
    is text. If you want to make a comment on some text, the usual practice
    is to add more text :)

    I wasn't able to find a comment bubble that contained anything, so I
    don't know what sort of information you expect them to contain -- every
    one I tried said "0 comments". But it seems to me that comments are
    superfluous, if not actively harmful:

    (1) Anything important enough to tell the reader should be included in
    the text, where it can be easily seen, read and printed.

    (2) Discovery is lousy -- not only do you need to be running Javascript,
    which many people do not for performance, privacy and convenience[*],
    but you have to carefully mouse-over the paragraph just to see the blue
    bubble, and THEN you have to *precisely* mouse-over the bubble itself.

    (3) This will be a horrible and possibly even literally painful
    experience for anyone with a physical disability that makes precise
    positioning of the mouse difficult.

    (4) Accessibility for the blind and those using screen readers will
    probably be non-existent.

    (5) If the information in the comment bubbles is trivial enough that
    we're happy to say that the blind, the disabled and those who avoid
    Javascript don't need it, then perhaps *nobody* needs it.




    [*] In my experience, websites tend to fall into two basic categories:
    those that don't work at all without Javascript, and those that run
    better, faster, and with fewer anti-features and inconveniences without
    Javascript.


    --
    Steven
  • Steven D'Aprano at Nov 27, 2010 at 11:58 pm

    Georg Brandl wrote:
    Am 27.11.2010 23:11, schrieb Steven D'Aprano:
    I wasn't able to find a comment bubble that contained anything, so I
    don't know what sort of information you expect them to contain -- every
    one I tried said "0 comments".
    Maybe you should have tried the page I recommended as a demo, and where Nick
    made his comments? :)
    Aha! I never would have guessed that the bubbles are clickable -- I
    thought you just moused-over them and they showed static comments put
    there by the developers, part of the documentation itself. I didn't
    realise that it was for users to add spam^W comments to the page. With
    that perspective, I need to rethink.

    Yes, I failed to fully read the instructions you sent, or understand
    them. That's what users do -- they don't read your instructions, and
    they misunderstand them. If your UI isn't easily discoverable, users
    will not be able to use it, and will be frustrated and annoyed. The user
    is always right, even when they're doing it wrong *wink*

    But it seems to me that comments are superfluous, if not actively harmful:
    (I've not read anything about harmful below. Was that just FUD?)
    Lowering accessibility to parts of the documentation is what I was
    talking about when I said "actively harmful". But now that I have better
    understanding of what the comment system is actually for, I have to rethink.


    --
    Steven
  • Alexander Belopolsky at Nov 29, 2010 at 4:07 pm
    On Mon, Nov 29, 2010 at 3:52 AM, Georg Brandl wrote:
    ..
    Yes, I failed to fully read the instructions you sent, or understand
    them. That's what users do -- they don't read your instructions, and
    they misunderstand them. If your UI isn't easily discoverable, users
    will not be able to use it, and will be frustrated and annoyed. The user
    is always right, even when they're doing it wrong *wink*
    That's right, of course. ?I really come to the conclusion that having a text
    link that "looks like" a link, i.e. is underlined, will have a better UI
    experience (since we cannot put notes "click bubble to comment" everywhere).
    Please don't make comment bubbles more visible. Doing so will only
    decrease signal to noise ratio. I think a little bit of a learning
    barrier is a good thing: it will keep down the number of "Bart was
    here" comments.
  • Steven D'Aprano at Nov 28, 2010 at 12:43 am

    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
  • Georg Brandl at Nov 29, 2010 at 8:59 am

    Am 28.11.2010 01:43, schrieb Steven D'Aprano:
    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.
    That is intended. I don't think many users will want to leave multiple
    comments at one time, and I put in that feature to actively discourage
    Columbo-style commenting. The field can always be brought back by
    re-opening the comment popup.
    "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.
    That is all noted, looks like I'll have to test the UI more with Konqueror.
    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.
    That is a bug and needs to be fixed.
    I would suggest that proposals should be visible by default.
    The problem is that they take a *lot* of space. But it needs to be
    more visible that there *is* a proposal.
    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.
    That's difflib for you. I don't really want to roll my own here.
    Performance really is poor :( There is a noticeable lag on even hiding
    and showing the smallest thing.
    A bit of lag is expected when loading comments, but inside the comment
    popup everything should be smooth. I know of problems with large pages,
    but if it's slow even on the math page, it seems that that browser is
    really behind in terms of JavaScript optimizations...

    Thanks for testing,
    Georg

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupdoc-sig @
categoriespython
postedNov 24, '10 at 9:23p
activeNov 29, '10 at 4:07p
posts15
users8
websitepython.org

People

Translate

site design / logo © 2019 Grokbase