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

[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.

> 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