From: Francisco B. <bo...@le...> - 2004-12-16 13:54:56
|
There were some remarks regarding the documentation some days ago, and I would like to add some of my own. I like your software very much and I write this in the intent of helping it to be even beter, please take my critics as constructive ones, that's how I hope they will sound to you. -------------------------- Often colleagues ask me how I made this or that figure, so I talk about pyx. There are 3 main remarks I make always to my colleagues: 1. it's a powerfull library putting python, PS and latex together with utilities for easy plotting; 2. it's hard to go through the documentation; 3. developers change the API with every release (breaking anything you might have done before). I have some suggestions regarding the last two: --------------------- About nr. 2: The way I see, the examples page is more of a show room for prospective users to look at than an actual tutorial. I would greatly appreciate if there were examples in the docs themselves. You don't need to include a throughout example but just a line or two showing how to use the particular class instance being described. I'm often re-reading the docs and going back and forth searching for an example of something in the examples page (and not finding it)... I mean: At times a picture is worth a thousand words and at times a code line is also worth many words. The "graph.style: Styles" page comes to mind when I think about something that I always have trouble with. ---------------------- About nr.3: While it's not stricly true that everything break after a new release, everything I have does break very often. I know that pyx is still alpha and you reserve yourselfs the right to change lot's but you must understand the burden that causes to your brave users ;-) Problem is: I don't do figures everyday, but every once in a while (paper, talk, conference etc) and everytime I discover I have to go through the Docs again because my own examples don't work anymore. It would help me terribly if you guys also produced a listing of things that got broken, just a listing would already help; a list and 2 lines: old API -> NEW API, would do wonders. Most of the doc text does not change in the upgrades and I find it difficult (and time consuming) to keep searching for whatever might have changed that might be screwing up my "new-release" broken code. Yes, I do save all EPS files... problem is I start new figures from older small examples that I have lying around. Perhaps if there was code examples in the docs that wouldn't be so much of a hassle. (I've tryed the changelog for that does not help much). ============ Sorry, for the long email, have to flee now, back on monday after conference... Peace, Francisco. |