Reference manual based on javadoc

[Martijn Dashorst <ma...@gmail.com>]

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

-- 
Buy Wicket in Action: http://manning.com/dashorst
Apache Wicket 1.3.0-beta3 is released
Get it now: http://www.apache.org/dyn/closer.cgi/wicket/1.3.0-beta3/

Re: Reference manual based on javadoc

[Martijn Dashorst <ma...@gmail.com>]

Yes I have considered this, but the problem is that the documentation
is not local to the class at hand. Therefore it again will get out of
date, and furthermore, the examples are not printable.

Martijn

On 10/5/07, John Ray <jo...@newonic.com> wrote:
> 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
> >
> >
>
>


-- 
Buy Wicket in Action: http://manning.com/dashorst
Apache Wicket 1.3.0-beta3 is released
Get it now: http://www.apache.org/dyn/closer.cgi/wicket/1.3.0-beta3/

Re: Reference manual based on javadoc

[John Ray <jo...@newonic.com>]

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
>
>