geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kevan Miller <kevan.mil...@gmail.com>
Subject Re: Documentation worries
Date Tue, 01 Apr 2008 18:13:43 GMT

On Apr 1, 2008, at 12:48 PM, David Jencks wrote:

> I tried to find instructions on connecting to an ejb from a non-ee  
> client in the 2.1 documentation and am rather discouraged at the  
> state of the 2.1 documentation.
>
> This is probably the first or second most common user list  
> question.  I couldn't find out how to do it from the front docs page.
>
> I'm also rather surprised at the contents of a lot of the  
> "Developer's guide" section.  Most of these articles I looked at are  
> about how to use the geronimo eclipse plugin, not geronimo itself.   
> Would it be possible to label the contents accurately and clearly  
> separate devtools documentation from geronimo documentation?
>
> i know quite a few people have been spending a lot of time working  
> on the docs but I'm worried that either through a bad table of  
> contents or lack of focus we may not be producing something that  
> actually answers many of the questions our users have.
>
> I'm certainly part of the problem, in that I often answer user list  
> questions directly rather than writing up docs.
>
> enough whining.  Anyone have an idea what to do?

Well, acknowledging that there's a problem, is a good start. It's part  
of a 12-step program... ;-)

There have been plenty of Eclipse/Eclipse Plugin user questions.  
Documenting these areas certainly seems like time well-spent. And  
certainly doesn't imply that other areas aren't equally/more  
important. There's still plenty to do...

I would think that problems with grouping/organization should be  
easily fixable.

Connecting to an ejb from a non-ee client seems like a good "samples"  
candidate (with corresponding documentation). Perhaps someone is  
interested in taking this on?

Documentation is one of those never-ending, sometimes thankless,  
critical tasks that we'll be continuing to refine. I think we've made  
a lot of progress and should be no great surprise that there's still  
plenty to do...

--kevan

Mime
View raw message