Quantcast

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

Skip Montanaro-3

    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

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

Georg Brandl-2
Am 24.11.2010 22:23, schrieb [hidden email]:
>
>     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

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

briancurtin
In reply to this post by Skip Montanaro-3
On Wed, Nov 24, 2010 at 14:24, Georg Brandl <[hidden email]> 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)

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

zipher
In reply to this post by Skip Montanaro-3
On Wed, Nov 24, 2010 at 1:24 PM, Georg Brandl <[hidden email]> 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 

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

Fred Drake-3
On Fri, Nov 26, 2010 at 3:52 PM, average <[hidden email]> 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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

Nick Coghlan
On Sat, Nov 27, 2010 at 7:28 AM, Fred Drake <[hidden email]> wrote:
> On Fri, Nov 26, 2010 at 3:52 PM, average <[hidden email]> 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   |   [hidden email]   |   Brisbane, Australia
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

Nick Coghlan
In reply to this post by Skip Montanaro-3
On Thu, Nov 25, 2010 at 6:24 AM, Georg Brandl <[hidden email]> 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   |   [hidden email]   |   Brisbane, Australia
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

Georg Brandl-2
Am 27.11.2010 13:05, schrieb Nick Coghlan:

> On Thu, Nov 25, 2010 at 6:24 AM, Georg Brandl <[hidden email]> 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

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

Georg Brandl-2
In reply to this post by Nick Coghlan
Am 27.11.2010 12:24, schrieb Nick Coghlan:

> On Sat, Nov 27, 2010 at 7:28 AM, Fred Drake <[hidden email]> wrote:
>> On Fri, Nov 26, 2010 at 3:52 PM, average <[hidden email]> 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

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

Steven D'Aprano-8
In reply to this post by Nick Coghlan
Nick Coghlan wrote:

> On Thu, Nov 25, 2010 at 6:24 AM, Georg Brandl <[hidden email]> 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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

Steven D'Aprano-8
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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

Fred Drake-3
In reply to this post by Nick Coghlan
On Sat, Nov 27, 2010 at 6:24 AM, Nick Coghlan <[hidden email]>
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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Python-Dev] [Preview] Comments and change proposals on documentation

Alexander Belopolsky
In reply to this post by Steven D'Aprano-8
On Mon, Nov 29, 2010 at 3:52 AM, Georg Brandl <[hidden email]> 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.
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Loading...