Moin, [ ... I tried to shorten some parts to keep this bounded from above ...]
On Mon, 27 Feb 2006, Michael J Gruber wrote: > Andre Wobst venit, vidit, dixit 2006-02-17 08:45: [ ... cookbook = FAQ + examples suggestion ...] > >> Would a wiki approach work for this ? > > > > In some sense I like the wiki approch very much in that it would allow > > our users to improve the situation in a way it helps *the* *users*. > > However, I think in the end we do not want some arbitrary list of > > comments. An editorial board which steamlines the descriptions would > > be best. For that I've started (well, several months ago) a system to > > provide descriptions to the examples. I would like to make the > > examples more cookbook-like. This doesn't really mean, that we need to > > change much in what the examples show, but we need to explain, what > > is going on. Most of the examples really have some deeper meaning, and > > my discussions (for example with Gert) have shown me several times, > > that it's very difficult for our users to look thru an example and > > really understand, what we want to show there. > > A cookbook doesn't necessarily show you everything. And it's also only > > a partial source for copy'n'paste code. But you can learn so much when > > some code really is explained. You may have a look at > > http://www.wobsta.de/pyxtest/examples/graphs/lissajous.html to see This is extremely nice and helpful! (and will be quite some work to do for all examples ...) > > what I mean. And the idea is to make it easy (for us) to manage the > > descriptions in order we really can do some editing. (Maybe somebody > > even want's to join us here ... this would be great!) The descriptions > > are very easy to write down (in a wiki-like style). Have a look at > > http://cvs.sourceforge.net/viewcvs.py/pyx/pyx/examples/graphs/lissajous.txt?rev=1.1&view=markup > > for the source of the description of the webpage cited above. > > > > That's the direction I do have in mind. Comments are welcome. Looks very nice - `lissajous.txt` almost looks like ReSt. (http://docutils.sourceforge.net/rst.html) But why not include this directly in lissajous.py as a doc-string (see also below). Then one has just one source and even when being off-line one has access to the full information? [...] > Also, the moderated wiki Andre mentions seems to be the best compromise > between openness to contributors and the goal of achieving a well > structured tutorial by examples. I only suggest substituting the > steamlining editors by streamlining ones ;) (sorry, couldn't resist...) ;-) Wikis tend to have the problem of getting unstructured, so this seems reasonable. On the other hand Wikis work because it is so easy to add things. Maybe one can introduce a staging area like WorkInProgress/Unfinished etc. to which anyone can add stuff. If something is considered to be good enough it gets integrated into the main Wiki structure. > Remains to see what to do with the FAQ and manual. Obviously, the list > of FAQ is organically grown. Some of the questions are "typical FAQ > questions". Part of the material from section 4 (plotting of graphs) > might rather be transferred to the examples. Getting the FAQ into the Wiki might lead to more people adding their tricks etc. It might also make moving things from FAQ to examples easier. > As for the manual I'm somewhat ambiguous. My personal experience is: > When I'm trying to understand concepts I find the section intros too > short and the list of methods and parameters overwhelming. When I try to > understand the details about how things fit together then I don't find > enough information in the manual. Most of the time I end up heeding Obi > Wan Kenobi's advice: "Use the source, Luke!" > > So, for the manual I suggest either restricting it to an API reference > listing the methods and parameters, or to extend the descriptions of > concepts. I think it's basically a matter of whether we want the overall > concepts (drawing is done on a graph instance, how do units work, paths, > decorators and deformers, ...) to be explained in the manual or in the > tutorial by examples. Presumably that is difficult to decide because both a manual and an API reference have their place. Have you thought about automatic API extraction from the source using doc-strings (maybe written in ReSt)? This brings me to another point: For any python library I am trying to use/understand I use the interactive capabilites a lot. Eg., with IPython In [1]: import pyx In [2]: pyx? [ ... doc-string snipped ...] In [3]: pyx.graph? <no docstring> In [4]: pyx.graph.graphxy? <no docstring> It would be nice if PyX would make more use of doc-strings. (For example, the description of graphxy in sec. 4.3 could essentially be copied/moved straight to the doc-string.) Best, Arnd ------------------------------------------------------- This SF.Net email is sponsored by xPML, a groundbreaking scripting language that extends applications into web and mobile media. Attend the live webcast and join the prime developer group breaking into this new coding territory! http://sel.as-us.falkag.net/sel?cmd=lnk&kid=110944&bid=241720&dat=121642 _______________________________________________ PyX-user mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/pyx-user
