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

[Georg Brandl]

Am 27.11.2010 13:05, schrieb Nick Coghlan:
> On Thu, Nov 25, 2010 at 6:24 AM, Georg Brandl <g.brandl at gmx.net> 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