On Thu, Nov 11, 2004 at 02:22:10PM -0500, Graham Fawcett wrote: > Mike Orr wrote: > >That's fine if you never upgrade, but code is subject to incompatible > >changes. You don't know which features the developers consider > >fundamental and which are accidental. Documentation is essentially a > >contract between the developer and the user, saying this is the > >recommended usage, and this API will not change without good reason and > >upgrade advice. Comments in the code could serve the same purpose, but > >in practice they usually don't. Documentation also serves to integrate > >modules and show how they work together. > > > > > I smell a documentation-writing volunteer... Neil, fetch the nets -- > before he gets away! ;-) Heh heh, I already had that in mind. When I get my application doing something interesting, I plan to package up a stripped-down version and a walk-through similar to "Running the Quixote Demo". I also want to put together a summary of the strategies I have found to work alongside the alternatives people have suggeted. Essentially, I just write what I would have liked to have read. I did the same for Cheetah and a bit for Twisted. > Seriously: perhaps moving the Quixote documentation to the Wiki would be > a good idea. Then, "write it yourself" would be a decent and meaningful > reponse to "the documentation is lacking". I was wondering if there's a wiki. Where is it? Wikis are excellent for presenting alternative strategies for various problems (e.g., the login, permissions, and slow query problems I had). However, for longer pieces of doucmentation (more than a page or two), wikis are inconvenient. - Browser UIs for TEXTAREA aren't suited for long pieces. - Wiki syntax is limited and every wiki has a different one. - It's difficult to upload/download a page (or all the documention in bulk) as "just the text, ma'am" without the pretty formatting. We have cookbook pages and a feature-wishlist page on the Cheetah wiki, and I used to copy tips into the Users' Guide (LaTeX) and move granted wishes to a "done" page, but that (and even finding new changes) got so tedious I stopped even looking at the wiki). I suppose I might as well write my stuff in ReST and y'all can put it in whatever format you want later. By the way, the existing Quixote documentation is pretty good. It's better than many if not most similarly-ambitious projects. I especially like "Running the Quixote Demo"; it does a pretty thorough job of explaining most of the features new users will care about. It's main problem seem to be the documentation not keeping up with the code. Oleg says this is why all documentation is futile, but to me it's just a bug in the documentation. With most projects the documentation (if it exists) is at least 75% right, and poking through the project history will uncover the reasons for any discrepency. To me the important thing is, a well-written tutorial makes the difference in terms of whether a program is widely used or not. I guess since Quixote seems to be in a long transition from 1.2 to 2.0, we'll need documentation for both tracks. I'll try out the alpha and see how it goes. I love how versatile and small Quixote is, how you can read through the whole source in an hour or two, and subclass anything you don't like without getting hit by untraceable problems. -- -Mike Orr (aka. Sluggo), mso@oz.net (iron@sense-sea-MegaSub-1-465.oz.net) http://sluggo.kicks-ass.org/ Cxu vi parolas Esperante?