Andre Wobst venit, vidit, dixit 2006-02-17 08:45:
> Hey,
>
> On 17.02.06, Simon Burton wrote:
>>> Basically, I think that a cookbook, i.e. a sort of merger of the present
>>> FAQ and the examples, would probably be most helpful for many users. The
>>> problem is that to do a good job, one needs a fairly good understanding of
>>> the examples and on the other hand some time to work on explanations. But
>>> this is certainly something which needs to be pursued and as far as I
>>> understand, some preliminary work has been done already (Andre knows more
>>> about this).
>>>
>> 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
> 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.
Following up on this discussion I'm moving this thread to a new one.
I do remember I offered help with the documentation quite a while ago,
and it didn't happen - for lack of time, but also for lack of
coordination. I'm still interested in helping out.
I like the new style of the examples a lot, especially the idea of
having one minimal example per section. I'm not sure if the set of
examples is compact or convex (attention: mathematician joking), but I
strongly feel there should be at least one minimal example per section.
The Lissajous example perfectly demonstrates how much one can learn from
concise code with a detailed description. Maybe one can add a little
more structure to the format of the examples, including something like
keyword subheadings ("paramfunction, context") which could be indexed
automatically. A good, structured set of examples in this style would
serve as the best tutorial one could imagine for the intended audience -
after all, PyX users are python programmers, whether they got hooked on
python by PyX or not.
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...)
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.
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.
Cheers,
Michael
-------------------------------------------------------
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
