I just took the time to look over the existing documentation found in the "Documentation" tab off the main qooxdoo site. Excluding content from the old site, there are a lot of really good pieces of information. Still needs restructuring.
What I thought would be nice is if the whole structure Derrell proposed could replace the documentation page (or appear as an immediate link under it) with it's existing content used as needed:
-=-
qooxdoo.org
Documentation
howto-manual-documentation-guide-handbook - as big as needed
tutorials - to the point demos, could be legible derivatives of the tests
FAQ - The familiar point form questions and answers
Conventions - things that don't pertain directly to qooxdoo functionality. Could hold other stuff (like this e-mail!).
Release Notes - Worthwhile, could be mixed with some other content like "notes from the developers".
-=-
Many of the current sections don't make sense and some of the information in them seems like it would be better suited elsewhere. It didn't take me long to map out places for the existing information. Stuff from the old site could easily be taken on a "need" basis...as I'm sure many things will be rewritten - better.
Here's my impression of the current "Documentation" tab-page sections & documents:
-=-
General - All of this seems like FAQ stuff.
Benefits - FAQ & selling points.
Features - Has a Table of Contents, could serve to start as a features page OR as part of a FAQ.
General - Should go into a FAQ
More... - Has nothing but the above
User - This name is slightly misleading. As the structure would be abandoned, I don't think it matters anyway.
First Step Guide - Things like this are great and merit a tutorials section. Sort of a "design pattern" repository.
Release notes - I'm not sure this HAS to be in documentation.
Widget visibility - The content of this page should be split and moved accordingly in the new structure.
Developer - Against the User category's name, this can be misleading...Aren't we all developers??
Inheritance - Advanced topic in the new howto
_javascript_ programming conventions - This could be kept, but somewhere else. Possibly alongside the FAQ
_javascript_ best practices - Same as programming conventions.
Modify object properties @ runtime - Topic in the howto
How to remove an event listener - Put in howto
Why don't we use CSS for appearance - I touched this document up the other day. I like it a lot. But it should go into a FAQ.
Writer - I understand what this section exists for, but it's hard to say if it is even needed 100%. Put it under "Help"?
-=-
Other observations....
- Things like "More..." just contribute to an overall sense of confusion. Documentation should never leave a cold trail.
- I would love to see the manual itself get into an object-by-object detail. Maybe as an appendix, offer a link to the latest build of the API documentation and then get busy describing things in there.
That's my CAD$0.02
_________________________________________________
Alexander Trauzzi
------------------------------------------------------------------------- Using Tomcat but need to do more? Need to support web services, security? Get stuff done quickly with pre-integrated technology to make your job easier Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________ qooxdoo-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
