Mailman 3 November 2010 - Doc-SIG

Re: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation
by Alexander Belopolsky Nov. 29, 2010

Nov. 29, 2010

On Mon, Nov 29, 2010 at 3:52 AM, Georg Brandl <g.brandl(a)gmx.net> 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.

1 0

Re: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation
by Steven D'Aprano Nov. 29, 2010

Nov. 29, 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

2 1

Re: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation
by average Nov. 28, 2010

Nov. 28, 2010

On Wed, Nov 24, 2010 at 1:24 PM, Georg Brandl <g.brandl(a)gmx.net> 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

4 4

Re: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation
by Steven D'Aprano Nov. 27, 2010

Nov. 27, 2010

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

1 0

Re: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation
by Nick Coghlan Nov. 27, 2010

Nov. 27, 2010

On Thu, Nov 25, 2010 at 6:24 AM, Georg Brandl <g.brandl(a)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(a)gmail.com | Brisbane, Australia

3 2

Re: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation
by Brian Curtin Nov. 26, 2010

Nov. 26, 2010

On Wed, Nov 24, 2010 at 14:24, Georg Brandl <g.brandl(a)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. > 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)

1 0

Re: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation
by skip＠pobox.com Nov. 25, 2010

Nov. 25, 2010

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

2 1

python-dbc (epydoc-based Design-by-Contract validator)
by Alex Myodov Nov. 9, 2010

Nov. 9, 2010

Hello, I would like to notify the community about the availability of new python-dbc module, allowing one to perform basic design-by-contract checks using the docstring definitions in epydoc format. No public releases has been done yet, but the home page with overall instructions is created at http://python-dbc.googlecode.com/ and the code is available at https://python-dbc.googlecode.com/hg/ (this is a Mercurial repository, use hg clone). At the moment, the primary functionality available is the validation of @precondition/@postcondition/@type/@rtype docstring fields in every function wrapped using @contract_epydoc decorator. The code is early, lacks a proper amount of unit tests and documentation, and definitely may have bugs for now, but it is stress-tested at the moment in internal projects, so far so good. The future plans include allowing to use the @contract_epydoc decorator to wrap the classes, thus making possible to add the support of @invariant fields in the class docstrings. -- With best regards, Alexander Myodov email: amyodov(a)gmail.com <mailto:amyodov@gmail.com> My LinkedIn page <http://ru.linkedin.com/in/amyodov>,^en MoiKrug page <http://honeyman.moikrug.ru/>,^ru LiveJournal blog <http://honeyman.livejournal.com/>^ru

1 0