Michael, thanks for taking the time to delve deeper into these issues.
On 05/07/2012 06:25 PM, elsdoerfer wrote: > > On 07.05.2012 08:39, MartinWittemann [via qooxdoo] wrote: > > What kind of documentation would have helped you? Do you think some > kind > > of overview could have worked for you? > > I just find the documentation generally to be often sparse, not > organized that well, and information spread over too many places. It's > not easy to put my finger one what I find wrong with it, but I'll try. > For example, there are lots of pages like this one: > > http://manual.qooxdoo.org/devel/pages/desktop/ui_overview.html > > Which explain concepts in a somewhat abstract form, but say little about > the actual practical usage. Ok, but I think pages like this make sense generally, because you usually will struggle with the "practical" pages if you haven't integrated the general concepts before. That being said, of course we need to know if the abstract pages are doing a good job for that, or if they're being too abstract, or not systematic enough, or not well enough integrated with the practical pages, or or ... > The pages I use use often (and sometimes > have trouble finding) are: > > http://manual.qooxdoo.org/devel/pages/widget/widget_ref.html > http://manual.qooxdoo.org/devel/pages/layout.html > Fair enough. Once you're beyond the basics, reference information is of most use. The manual has to cover both. > But it's subpages only contain very rough descriptions of the widgets, > and no actual code samples either. For some widgets the API viewer has > basic usage sample, but often it doesn't, so you look at the code in the > demo browser to see how they are used (which btw, I just tried to find a > link to the demo browser on the site, and couldn't). As Martin already wrote, we need to break information up between several contexts: - the manual - the API documentation (Apiviewer) - the snippets/demos/Demobrowser Again, the interesting question for me is if we are doing a good job at this. The API documentation is *mainly* a pure reference, basically a very long list of class names, their attributes and parameters. You really want this to be complete and exhaustive, and authoritative when it comes to the nitty-gritty of signatures. It has also the highest chance of being up-to-date as it is maintained with the code. If you look at young projects, this is often all they provide. But you really cannot leave it at that. You need "user guide" type information, how to use all these APIs. I'm in favor, and I think there is some sympathy for this direction in the project, to actually *add* simple, low-level user guide information to the API docs. You can see traces of this in some class and package documentation in the Apiviewer [1], [2]. I would even vote for a simple code snippet for every method as part of their standard documentation. But all this only takes you so far. There are things on a higher level which cannot be dealt with satisfactorily on the API level. That's where the manual comes in. Its first purpose is to fill in on the background material, introductions, tutorials, and otherwise provide the information that would be ill-suited in the API ref. Its main purpose is user guide info. The last area are the demos. It would be nice to have a running example of each and every API in the Apiviewer itself, but this would overload the Apiviewer (performance-wise), and some things are better demonstrated in the context of a little application anyway. The demos can cover more of how classes play together than the API ref, and can do so more accurately and up-to-date than the manual, as they are actually built and run. To maintain these three contexts and make them well integrated is the main (and a major) challenge. And cross-linking is one part of this integration effort. Any concrete hints (up to pull requests) on how to achieve this are highly appreciated. [1] http://demo.qooxdoo.org/current/apiviewer/#qx.io.remote [2] http://demo.qooxdoo.org/current/apiviewer/#qx.util.AliasManager > But even if the virtual widgets remain separate, I think I would > actually prefer them in a separate virtual.* package. Part of the > confusion for me was the namespacing: There is a form.List and a ui.List > - If I build a "form", possibly even using qx.ui.form.Form, do I have to > use form.List? Is list.List inherently unsuitable for use in a form? > Shouldn't I use it together with other widgets from the form.* > namespace? tree.Tree seems to be, in terms of the > namespace-organization, a sibling of list.List, and yet one is virtual, > the other isn't. I perfectly understand. Sometimes these issues are the result of at least debateable design decisions, and naming and namespacing is an ongoing discussion within the project. But the obstacles are high. You mentioned backwards compatibility elsewhere. Even if we want to deprecate a namespace, we need to introduce the new namespace(s) and still keep the old one, for at least one minor revision so you have duplication of some sorts in the class hierarchy. If we then also want to introduce new concepts that should eventually replace the old implementation (like the virtual widgets) things get even more wobbly. Then add that the new classes are not finished by the time they appear in the framework, but require a number of cycles of developing, feedback, fixing and refinement to eventually get there, so you have varying degrees of "ripeness". Then this work of developing is interrupted every now and again as our resources in the team are contested. Our experience is that it takes quite some while before the new classes can actually *replace* the old, so for some time you will use either-or (or even both!), depending on your application needs. And all the way you have classes with overlapping semantics in the framework... This all is not to say it's good, but just to give you some background on how this happens. > Still, writing this, I did have one potential idea: Because one other > thing that has bothered me with the widgets are the unnecessarily long > package names to access them. For example, to use a Label, I need to > remember it is in qx.ui.basic. If a need a DateChooser, I need to > remember it is in qx.ui.control. Some things are in qx.ui.form, other > have their own subpackages (qx.ui.groupbox) etc. In practice, I often > have to look it up. > > Why not use make everything available (and document it as such), as > qx.ui.DateChooser, qx.ui.Label, qx.ui.VBox etc? Internally, it might > still be qx.ui.basic.Label, except the user wouldn't know about it. > > If one ever where to decide on a redesign of the namespace/widget > organization, this might offer a way to do this without breaking > backwards-compatibility: Pull the one List, Tree etc. widget that people > are supposed to use into qx.ui.*, but the full names still work. I distinguish between code organisation (the way the framework developers see it) and the published API (the way the qooxdoo users see it). For code organisation I'm highly appreciative of the nested namespaces. It's not the only way, but since qooxdoo started that way we should strive for a good and consistent implementation of classes in namespaces. And don't forget that this is familiar ground for all those coming to qooxdoo from backgrounds like Swing or Qt. It's also largely a matter of taste, previous experience and available tools. If you had an IDE that auto-completed qooxdoo class names you probably wouldn't find them so bothering. If you use the search tool of the Apiviewer, finding the right package name of a given class is fairly easy. That being said I have no problem with providing *additional* APIs for users to work with. In fact, we are just working on one, (q). These could be used alternatively to the classical classes, even predominantly. I actually would encourage you to implement exactly what you suggested as a qooxdoo-contrib project. Shouldn't be very difficult to map existing functionality to new classes. But I would be hard-pressed before giving up on the internal structure of the framework. Hope this makes some sense. T. ------------------------------------------------------------------------------ Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ _______________________________________________ qooxdoo-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
