Have you considered merging the documentation into the examples app
where each example has a little bit of documentation? This would create
a kind of wicket by example manual where you could start at the top with
Hello World and work your way down. You could also use it as a reference
manual when doing development. So if you want to create a form just go
to the form example, read the documentation and then copy the code into
your application.
The main index page would be similar to the existing example app. My
only suggestion would be to better organize the examples into sections
with indents on a single page. That would make it easier to find a
specific example as you could just search for "border" on the main page
rather then currently where you have to know it's on the component
reference page.
For each example you could create a framed HTML page. The top half of
the page would be the live demo. The bottom half would have a
TabbedPanel with the first tab containing the documentation for the
example. The other tabs would have the source code. Being a frame you
could of course resize the frames to get a bigger view of either the
live demo at the top or the source code.
One other feature that would be really nice is if you could edit the
java or html source code of an example. The examples framework would
then compile the code and redisplay it in the top half of the page. Due
to security concerns I think this option would only be available when
the examples are run on a user's local machine. Although it might be
possible to host this with VMWare. You'd have to pass off custom code to
java running inside of VMWare then monitor the JVM through the debugger
interface and kill the JVM if the user spawns threads, has a while loop
then never exits, etc.
John
Martijn Dashorst wrote:
All,
We all know we suck at writing docs, even though we have several book
authors in our midst.
There are some problems I see with maintaining a separate reference manual:
- base format -> docbook is a nasty piece of work to write, latex is
somewhat better, word is not multi-user
- recency -> the docs are pretty soon outdated.
If we are able to get a single point of definition, then that would be
a killer IMO.
It should be possible to generate a reference manual based on our
javadocs. If the descriptions for classes are written correctly we
only have to maintain the javadocs, and generate a pdf and website
based on that.
We don't have to generate the document for *all* classes, we can
create a ToC based on whatever classes we wish to include, and group
them in everyway we see fit. With maybe some extra javadoc annotations
we will be able to select particular methods that are of interest for
the reference manual, whilst ignoring the rest of them.
There are several doclets that allow you to generate PDF's, latex or
docbook as an output format. http://doclet.com is the cannonical list.
What do others think?
Martijn
