"Erik A. Onnen" <[EMAIL PROTECTED]> writes:
> Derrell,
>
> Thanks for the helpful post, but I think your response echoes the OP's
> point that more needs to be done towards documentation.
Yup, that's exactly what I stated in my first response:
In 'namespaces', there is "better" documentation and a much better method
of finding/viewing the documentation. From a user perspective, though,
there's still a *very* lot that can be done to document overall usage
vs. usage of a particular function or class. Having someone like you
dedicated to writing user documentation would be wonderful!
So yes, you are absolutely right. *Much* more needs to be done towards
documentation!
> Not only is the namespace documentation light to non-existent, but the
> documentation you site on how to generate the documentation is out of
> date. I tried following the steps listed at
> 'http://qooxdoo.org/documentation/developer/api_documentation' and the
> structure of the subversion tree has changed. The better way to do things
> from what I can tell is to enter the 'frontend' directory in the source and
> perform a 'make docs' (frontend vs. backend isn't even discussed in the
> referenced link, nor is the make file). Unfortunately, after I figured that
> out from parsing the makefile, running 'make docs' still didn't help because
> the docs point us to 'source/demo/apiviewer/index.html' which does not
> exist. I found what I think the viewer should be at
> '/frontend/api/build/index.html' but opening that produces a popup window
> with loads of errors and no documentation that I can actually view. After
> all that effort, my interest in getting the docs working for the namespaces
> API is all but gone and sadly I've given up and gone back to cranking dojo
> widgets.
Sigh. Yes, there have been announcements on the mailing list that the
'namespaces' branch would be highly unstable for a week or so while it is
prepared for moving into 'trunk'. I haven't tracked what exactly is going on
during this process, but yes, Sebastian and Andreas have been doing extensive
work on getting the API documentation system (and the code structure) "ready
for prime time". I had noticed that the new "frontend" directory was created
and that lots of Makefile and script work was being done, and I should have
mentioned that. My error.
> The lack of API (the examples are great) docs is one of only two things
> keeping me from using Qooxdoo straight away. Sure, it's a volunteer effort
> and I understand that but the lack of docs is an huge barrier to entry for
> those interested in helping out. If Qooxdoo is the best toolkit available
> and nobody but the devs can figure out how to use it, Qooxdoo will join a
> long list of projects that were great but never reached their uptake
> potential. I truly think Qooxdoo is the best paradigm for rich ajax
> development out there right now, but sadly I can't recommend using it to my
> customers due to things like the documentation issues and this dead zone
> between the 'no new development' 0.5.x branch and the 'no releases or docs
> yet' namespaces branch. </rant>
You are echoing much the same issue that Alexander brought up in his posting.
Although the API documentation should be much improved in this new version, it
is likely still not enough. Also, API documentation alone is inadequate for
users to use qooxdoo for development. There must be "How To" documents that
explain the structure of a qooxdoo application, how to create widgets (in
general) and what widgets are available. Much more information about the
events which are dispatched by each widget (and when) is needed. Yes, there's
lots of work to do! Alexander was volunteering to help on the documentation,
and my posting immediately previous to this one was to answer his questions
about where to look. (Unfortunately, I got the API documentation answer
wrong, since it just changed.)
Erik, do you have any desire to help document qooxdoo? There is enough to do
that we could certainly use additional people helping! Dividing the work up
into manageable parts and distributing the parts to interested contributors
would be a good way to accomplish this. Initially, developing a documentation
roadmap might be a good way to start. It could be an outline of the various
types of documentation (needed and already existing). Alexander has already
offered to help. If you are offering as well, that'd be awesome! One of us
who knows the code could help coordinate.
Let's continue this discussion!
Cheers,
Derrell
-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys -- and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
qooxdoo-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
