Mailman 3 January 2006 - Doc-SIG

Re: [Doc-SIG] [Python-Dev] that library reference, again
by Edward Loper Jan. 27, 2006

Jan. 27, 2006

Robey Pointer wrote: On 30 Dec 2005, at 18:29, Christopher Armstrong wrote: >> [epydoc] is not really even "good enough" for a lot of my usage without some >> seriously evil hacks. The fundamental design decision of epydoc to >> import code, plus some other design decisions on the way it figures >> types and identity seriously hinder its utility. [...] As a side note, I've done a significant amount of work on a newer version of epydoc that supports both inspection & source-code parsing (and can merge the info from both sources, if they're available). Hopefully this new version will address some of these concerns (and some other issues I've heard raised). But I haven't had time to work on it in a while -- I need to concentrate on getting my phd thesis done. If anyone is interested in working on this new version, just let me know. :) -Edward

1 0

regarding the current state of Python docs
by John M. Gabriele Jan. 25, 2006

Jan. 25, 2006

Hi, I've just joined this list, and judging from some of the posts I've seen in the archives, there seems to be some concern about a problem with the current way Python is documented. My guess is that the current system looks something like this: 1. checkout the doc source 2. make changes 3. commit changes Personally, I think the best way document Python (outside of the built-in docstrings) is a wiki but with only a select group of folks with edit privileges. That is, only after you've been around for a little while (or otherwise shown that you can write good docs and want to help) are you given edit access. Nothing too strict. Just limited to folks who actually want to help, and who can show they're fairly good at it. The same way you grant committer access on any free software project. It seems like it wouldn't *too* be much trouble to simply take all the docs as they currently are and export them to a new wiki, wholesale. That is, create a "sister" wiki to the one we already have. Put the whole enchilada on there. The library reference, the language reference. Everything. Editing a wiki page is *way* easier than doing the checkout- edit-commit procedure as outlined above. Sometimes I've only got 5 or 10 minutes, and really would like to see a small clarification in the docs. If it were wikified, I could make that change (say, on my slashdo^H^H^H lunch break). If I'm at work, and had to do a checkout, etc, ... no way would I bother. It would have to wait 'til I get home -- then with the wife and kids wanting some family time, the edits might not even happen. How hard is it to convert html to suitable moinmoin wiki text input? Is there already a tool for this? Maybe someone needs to just jump on it, pull the starter on the chainsaw, just go for it, and let the chips fall where they may. :) ---J __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com

2 4

Installing Python modules doc -- please add a few items
by John M. Gabriele Jan. 16, 2006

Jan. 16, 2006

I just sent the following {see below} message to docs at python.org, but then discovered this ML, subscribed, and am re-sending it to this list: Request for possible additions to the "Installing Python Modules" doc: 1. When I want to install a package in 2 steps, first building in a separate build dir (--build-base=~/temp/foo) then install in my own packages directory (--home=~/python_pkgs), please mention in the doc how setup.py knows I've already run the build. That is, when I tell setup.py to install, how does it know that I previously ran a build, and where those build products are waiting? 2. At the very beginning of the doc, you might mention the difference between installing a single module, and installing a package containing a number of modules. That is, do developers use distutils when they are providing only one module (as opposed to a package full of modules)? 3. It might also be beneficial to note in the doc why you run the command as "python setup.py" instead of "./setup.py". 4. It would be nice to have a comment about what lands in your '--build-base' when you've got a package that only contains some pure Python modules. I guess setup.py simply copies the .py files to the build directory? I could make these changes/additions myself, but would need to know: A. Where to get the source from, and B. The answers to the above questions. :) BTW, I don't know if this message is going to a ML or not. If it is, and I need to subscribe to get a reply, please point me in the right direction. Thanks, ---John __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com

2 1

PyCon
by David Goodger Jan. 11, 2006

Jan. 11, 2006

PyCon TX 2006 is coming up, Feb. 24-26, in Addison/Dallas Texas USA. http://www.python.org/pycon/2006/ Registration is now open, and early-bird pricing is in effect until Dec. 31: http://www.python.org/pycon/2006/register.html Be sure to book your room at the conference hotel: http://www.stayatmarriott.com/Pycon2006/ There will be three Docutils-related talks: * Docutils Developers Tutorial: Architecture, Extending, and Embedding (David Goodger & Felix Wiemann) * Easy Slide Shows With reStructuredText & S5 (David Goodger) * What is Nabu? (Martin Blais) List of talks with summaries: http://wiki.python.org/moin/PyCon2006/Talks I will be giving a tutorial on the day before the conference, Feb. 23, in the morning: Text & Data Processing (http://wiki.python.org/moin/PyCon2006/Tutorials/TextProcessing). List of tutorials: http://wiki.python.org/moin/PyCon2006/Tutorials We will hold a Docutils sprint in the four days following the conference: http://wiki.python.org/moin/PyCon2006/Sprints/DocutilsSprint . Other sprints & info: http://wiki.python.org/moin/PyCon2006/Sprints Tell your user group. Tell your friends, classmates, and colleagues. I hope to see many of you there! -- David Goodger <http://python.net/~goodger>

2 1

Released: Docutils 0.4
by Felix Wiemann Jan. 9, 2006

Jan. 9, 2006

======================= Docutils 0.4 Released ======================= Docutils 0.4 has been released. You can download it from <http://prdownloads.sf.net/docutils/docutils-0.4.tar.gz?download>. What Is Docutils? ================= Docutils is a system for processing plaintext documentation into various useful formats, such as HTML or LaTeX. It includes reStructuredText, the easy to read, easy to use, what-you-see-is-what-you-get plaintext markup language. Major Changes Since The Previous Release (0.3.9) ================================================ * Added an S5/HTML writer and the rst2s5.py front end: multi-platform, multi-browser HTML slide shows. See <http://docutils.sf.net/docs/user/slide-shows.html> and <http://docutils.sf.net/docs/user/tools.html#rst2s5-py>. * The newlatex2e writer is nearing completion. * Added a DocTree reader, ``publish_doctree`` and ``publish_from_doctree`` convenience functions, for document tree extraction and reprocessing. * Added directives: "container" (generic block-level container), "default-role" (role used for `backtick` syntax), "title" (document title metadata), and "date" (generate the current local date, for substitution definitions). See <http://docutils.sf.net/docs/ref/rst/directives.html>. * Length units are now supported for image sizes; see <http://docutils.sf.net/docs/ref/rst/directives.html#image>. * Added standard definition files for special characters etc.; see <http://docutils.sf.net/docs/ref/rst/definitions.html>. * Added Japanese and Simplified Chinese language mappings, and support for double-width CJK-characters in tables and section titles. * Added a guide for distributors (http://docutils.sf.net/docs/dev/distributing.html) and a guide for developers (http://docutils.sf.net/docs/dev/hacking.html). * Added significant Emacs support for reST; see <http://docutils.sf.net/docs/user/emacs.html>. * Added a --strip-comments option; see <http://docutils.sf.net/docs/user/config.html#strip-comments>. * --embed-stylesheet is now the default for the HTML writer (rather than --link-stylesheet). Compatibility Note ================== Docutils 0.4.x is the last version that will support Python 2.1. Docutils 0.5 will *not* be compatible with Python 2.1; Python 2.2 or later will be required. Docutils 0.4.x is the last version that will make compromises in its HTML output for Netscape Navigator 4. Docutils 0.5 will require more up-to-date browsers (the exact definition is to be determined). -- Felix Wiemann -- http://www.ososo.de/

1 0

Re: [Doc-SIG] that library reference, again
by Ian Bicking Jan. 9, 2006

Jan. 9, 2006

Fredrik Lundh wrote: > (I'm not sure if it's python.org or gmane.org that has trouble right now, > but something's wrong somewhere. let's see if this works better) > > Ian Bicking wrote: > > >>>fwiw, I'm not convinced that we need a tracker at all. A mailing list >>>and a way to link to documentation constructs (with links that can >>>be read and written and followed by humans, and identified by com- >>>puters) might be good enough. >> >>I think there needs to be at least some workflow, some way to indicate >>what comments have been acted upon and which ones have not. How else >>can multiple people maintain the documentation? There's no >>collaborative way to track the status of email messages. > > > I somehow assumed that the maintainers would use email to report back to the > list ;-) > > the problem here is to strike a balance between tracking and discussing; trac > and roundup etc are great tools if you want to track progress for > distinct issues, > but they're not that great for discussions, especially when you don't > know up front > if the discussion is going to result in a single issue, a dozen > issues, or nothing > at all... Roundup is pretty good for discussions, since it has an email gateway. I think Roundup would be just as good a choice as Trac. A gateway doesn't deal with the case when a single discussions involves many tickets (or vice versa), but I think ad hoc ways to deal with that (e.g., create a new expansive ticket, or just track it manually) are generally fine. That said, I've also seen people usefully discuss things on trackers, it's just not the default. The main workflow issue I see is how to defer work without forgetting it. I know I personally am horrible at doing this with email -- if I don't handle it right away I forget about it. Assignment can be quite useful in collaboration, when you want to either say "I am working on it", or "you should work on it", and doing that in email is also hard, especially more than once (you have to find the latest assignment-related email to figure out who has the ball). Also, discussion doesn't seem primary to this. Most comments can probably be acted on directly with no discussion. So optimizing for discussion seems wrong. -- Ian Bicking / ianb(a)colorstudy.com / http://blog.ianbicking.org

1 0

Re: [Doc-SIG] that library reference, again
by David Goodger Jan. 9, 2006

Jan. 9, 2006

[David Goodger] >> The second sentence lacks a rationale. What's wrong with "-- >> dashes"? What's "silly" about "``quotes''"? [Fredrik Lundh] > don't you know *anything* about typography ? Yes, for a layman, I know plenty. I am not a typographer though. Simply put, your "list of goals" provides no context for your statements. *I* know that "--" is turned into an en-dash in TeX, and that "``these''" are turned into curly quotes. So? What's "silly" about that? Spell it out, man! And what about 99% of the people who read your page? They won't know the first thing about what you're talking about. >> The reference to ReST is wrong here; ReST certainly can know the >> semantics of a given identifier. > >> I don't think you understand ReST except superficially. > > That's why I'm listening to people who've tried to use ReST for this > purpose. They've all failed. Maybe they also only understood ReST > superficially. Perhaps, since ReST is *not* designed as a semantic markup language. It's designed as an implicit markup language, with explicit extensions for semantic markup. In any case, ReST is *not* being proposed here. > Or maybe it's because ReST is created by people who have a very > shallow understanding of the issues involved in writing structured > reference documentation. Your guess is as good as mine. Why does Fredrik find it necessary to descend to personal insults? Your guess is as good as mine. > Support for quick turnaround, edit via the web, richer semantic > information, and a larger existing toolbase isn't better than the > status quo ? Those would be good features. Those features are not mentioned in your list of goals though! (http://effbot.org/zone/pythondoc-lib.htm) AFAICT, you just went off on a tangent to create a new markup language, which we don't need. > The problem is that the WORKFLOW doesn't work. So fix the workflow. Something like Ian Bicking's Commentary system, or something more specific to Python's docs, seems to fit the bill. > It's the workflow that's the real problem here, but you cannot fix > the workflow without fixing the markup. I disagree. The markup doesn't need an overhaul to fix the workflow. > I assume this means that we're going to keep getting more "ReST can > certainly do this but we're not going to show anyone how" posts from > the ReST camp ? You assume incorrectly. I'm not talking about ReST. I'm not proposing ReST for anything. Please ignore the fact that I'm the author of ReST; I never brought it up, I never proposed it. *You* are the one harping on it. I'm just against an arbitrary and unnecessary change of markup in Python's docs. > Your reply makes it obvious that you don't understand the issues > involved here, nor how the goals address them. Your reply, and your regular descent to personal insults, make it excruciatingly obvious that you're a troll. I hesitated before first replying to this thread, suspecting (from past experience) that this would be the response I'd get. From now on, I'll avoid feeding this particular troll. > I'd say that the fact that you're asking this should disqualify you > from ever working on documentation tools again... Your writing malicious crap like this ought to disqualify you from ever participating in python-dev discussions again. Fredrik, we all know that you you are a superb developer who makes wonderful contributions to Python. We also know that when faced with disagreement (and sometimes, seemingly, without any provocation at all) you are a malicious prick. -- David Goodger <http://python.net/~goodger>

4 7

Re: [Doc-SIG] that library reference, again
by Fredrik Lundh Jan. 8, 2006

Jan. 8, 2006

> anyone knows anything about support for semantic markup ? http://meta.wikimedia.org/wiki/Semantic_MediaWiki not sure a full-blown RDF-in-wiki-syntax is really that optimal, though ;-) </F>

2 1

proposal: a process for solving the Python Documentation Problem
by Chad Whitacre Jan. 8, 2006

Jan. 8, 2006

Dear All, Here is an attempt to outline a process by which we might clarify and solve the "Python Documentation Problem." The attempt here is to work from the outside in, starting with the end result we want to see, and working backwards from there to find the best solution. 0. Agree on a problem-solving process. :^) 1. Decide what documentation is in scope: Library Reference only? Language Reference as well? Everything? 2. Brainstorm the end-user formats we might possibly want to read documentation in: HTML, PDF, plain text, etc. 3. Prioritize formats. 4. Crop the list to three or fewer primary target formats. 5. Define the information that needs to be encoded to support the given formats. 6. Identify the storage format that best balances ease of migration, maintenance, and authoring with adequacy to the task of encoding and making accessible the necessary information. 7. Build, borrow, or buy the tools to migrate, maintain, author, access, and transform the information. 8. Migrate, maintain, author, access, and transform the information. chad

2 1

Improving the documenting process.
by Laura Creighton Jan. 3, 2006

Jan. 3, 2006

Chad suggested I post this reply to him back to doc-sig, and see if there are others like me who think that the python documentation problem centres around 'not enough good documentation being produced' and a process that is opaque, has bottlenecks, and excludes the very people who would be best at writing good documentation, because they aren't python-language developers. I thought to shorten it, and then thought, what the heck, maybe some other people would be interested in what I was doing in the 80s. Sorry that this will bore some others. Happy New Year, Laura ------- Forwarded Message Laura Creighton wrote: > In a message of Sat, 31 Dec 2005 22:13:02 EST, Chad Whitacre writes: > >>Laura, >> >>Thanks for giving me an opportunity to clarify my proposal. > > >>On the other hand, I confess that I don't follow your suggestion that >>separation of "logical" and "rendered" information leads to a plain text >>base format, one without any markup. Why exclude markup that is semantic >>rather than presentational? > > > Oh yes. This may not be well-known. I keep forgetting. > > Because authoring is an art. What you need are tools that support > the process of composing excellent prose. All of the structural > markup greatly hinders the process. In exactly the same way that > all the curly-braces-and-semi-colon junk in languages we know and > hate, all there for the benefit of the compiler, detract from writing > well. The more intrusive the markup, the worse the prose. (Which > has been measured in places like the lab I worked in in the 80s.) > > There is still hot debate in some circles as to exactly why this is > so, but the prevailing theory is that good prose is dependant on using > the part of your brain that listens. So most people really have to > 'hear the words in their heads' as they write in order to create the > best prose. (And some do not. Why this is so is unknown.) But when > they start fiddling around with the presentation details at the same > time as they are writing the text in first place, their attention is > divided and the texts are significantly worse. > > So, when we stuck people into our labs and measured them, our standard > for 'how people write' was 'using emacs or vi and the MS macro > packages for troff'. And it was clear that people were producing > pretty rotten texts. So we measured how well they wrote if they > just used vi or emacs, and skipped the markup. And for most people > this produced a significant improvement. At this point, believing I > was onto something, I went out and founded a computer company, SoftQuad, > with a bunch of friends of mine in the publishing business. Device > Independent Troff was new, laser printers were new, bitmapped displays > were new, and Apple was promising this thing called the Macintosh. We > thought that we had the killer app. A WYSIWYG editor, though I don't > think we called it that. Without evidence, we were convinced that we > knew why it was that people wrote poorer text when using troff, and > that had to do with it being hard to use the macro packages. > > And this goes to show that 'it ain't the stuff you don't know but > the stuff you know that ain't so' that really hurts you. Because this > was one of the more spectacular cases of 'completely getting it wrong'. > We made an editor (actually two -- a moded one which we gave the vi > bindings and a modeless one which we gave the emacs bindings) and then > took our usual suspects of university students in the humanities who > already knew vi or emacs and had them go at it. > > They were very happy to not have to learn the MS macro set. But to our > dismay, the prose still ended up rotten. We'd solved the wrong problem. > And the very best results were still being had by authors that used > whatever text editor they liked best to compose text, and then handed > the work to somebody else -- a compositor if they were dealing with > our Dead-Tree-Printing Office, or the secretaries of the Political > Economics department if you were a student or a professor there. > Making the thing look good on paper -- or on the screen, was then > somebody else's job. But even if you composed the text first, and > then made a second pass after you got the text down correct you would > end up with a better result than if you composed and composited > simultaneously. Next we discovered that most people wrote better > if they wrote with somebody else. (For non-fiction. For fiction we > couldn't come to any conclusions except that we needed to study the > cognitive process of writing fiction more.) On the other hand, documents > designed by committee almost never were well written unless the > committee met, decided on the structure of the document and what > its content was to be, and then let one or two people actually write > the thing. > > >>Also, you hint that it might be helpful to define the problem itself >>more clearly, and I agree. The problem I want to see solved is >>Fredrik's: how do we cut the documentation workflow cycle down from 3-6 >>months to, say, 3-6 days? > > > This is a fine goal. But I think our problem is that we do not have > enough high-quality documentation, and that the people who find problems > with the documentation do not have an easy way to discuss this with > other people who are interested. Submitting a bug report only means > that people who are reading the bug tracker get to be informed. This > excludes the bulk of interested people. > > If you haven't read the Kruger Dunning Report _Unskilled and Unaware of It_ > http://www.apa.org/journals/features/psp7761121.pdf I suggest you go read > it now. It applies with particular vengeance to authoring skills, most > especially in people who are writing in their native language. Ability > in language usage it not particularly bell-curved. Both ends have > relatively large numbers when compared to the population at large. > Excellent writing ability is something that people have selected for > to such an extent that the right end is greatly increased, while > non-native speakers, and people with learning disabilities end up making > the left end chunkier as well. > > Which sadly means that the it is not just the lowest octile of language > users who lack the cognative abilities to judge their performance. In > our labs we found it remarkably easy to produce samples of people where > 80% of the people in the room did not write very well, according to the > judgement of the top 2%, but nearly all of that 80% believed that they > wrote 'rather well'. > > This makes the whole process of criticise-and-rewrite even harder than > it already is, which is hard enough in the first place, and makes a > bug tracker a particularly difficult place to raise your issues. There > is no particular good way to say 'could I have a different python > developer to discuss this with? This one is not skilled enough to > understand me'. The more confused you are, and the harder time you > have expressing and understanding your confusion, the worse it becomes. > (It is hard on the unskilled python developer, as well. He really has > no way to tell the difference between things he cannot understand because > he lacks the skills, and things he cannot understand because the person > who posted the idea lacks the skills, and plain old bad ideas.) > > One of the more frustrating things that I have seen happen again and again > is where some new person, who doesn't understand how to do something, > complains about the documentation. All too often the response that this > person gets centres around 'explaining to the newbie how the code > really works and how the newbie should have solved his problem'. This > drives the newbie, who already has solved his problem up the wall. > He doesn't want help in learning things, he wants different and > better documentation. > > He may even have a fix. But the fix is often going to be poor. It > may solve this problem, but it leaves things more confusing for others > in some way. This does not mean that the existing documentation is > adequate. It means that somebody who is both aware of the code > involved, and who is aware of the newbies problems in comprehension, > needs to rewrite the documentation. > > Now it may be that such people are rare in general. I think they are > rarer among computer progammers than in the population at large. But > I think that our structure exacerbates our problem. If you re-read > http://mail.python.org/pipermail/doc-sig/2005-December/003466.html > you will see Fred Drake assert that: > > 'comments from the release X.Y.Z docs need to be handled before > releasing X.Y.Z+1 or X.Y+1.*, or they aren't being used to improve > the documentation at all' > > which is either trivially true, or the indication of a larger problem. > This looks to me as if documentation releases are delayed until every > (a large number? enough?) comments are handled, which strikes me > as a very large bottleneck. Wikipedia is proving that you can do > continuous updates on documentation. Do we need them? Would we > get more people working on improving the documents if the live > version was a mediawiki? > > I think the question of 'what do we need in order to share and > collaboratively work on documents more effectively' is the one that > we need to solve if we want more rapid turnover. So I would say > that our workflow doesn't need _shortening_ so much as _transforming > altogether_. And I don't think I understand exactly all the steps > we have now, so it would be nice if somebody who knows this very well > would post them. Then we could analyse them, and see why it is that > we perform the way we do. > > Laura ------- End of Forwarded Message

5 5