geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hernan Cunico <hcun...@gmail.com>
Subject Re: Documentation worries
Date Tue, 01 Apr 2008 17:37:35 GMT
David,
I don't see the problem with the content we currently have. The problem I see is with the
content we don't have.

Everybody is welcome to contribute to the documentation, I ask for contributions and start
discussions all the time. To have a healthy documentation we need the community involved in
it as well.

The goal of the Developer's guide is to provide users with enough information so they can
develop applications for/with Geronimo. Topics covered in this guide include setting up the
development environment, GEP is part of the development environment. I would love to have
more coverage on maven plugin and netbeans whenever the plugin is ready. Anybody that knows
how to do this, pls don't by shy and chime in.

The last section in the Developer's guide provide a series of tutorials with detailed steps
and tons of screenshots on how to do things from scratch. And yes, most of them using GEP;
I personally think GEP is great and can't wait to see it officially released. The more people
contributing to the doc, the less personal it would be ;-)

I see devtools as one of the building blocks for the developer's guide. If we take out devtools
( and here I include maven and others ), what's left for developing applications for Geronimo?

What other specific content would you like to see in the Developer's guide?

The User's guide, on the other hand, is centered ( although not exclusively ) on administration
and configuration and it also provides a series of sample applications. Connecting to an EJB
from a non-ee client would be a good candidate for a sample application.

I agree with you that we are not in great shape with the doc. We all need to get more involved
if we want to make it better.

Writing docs take a lot of time and for most people it's a "horrible" experience to go through,
specially when I'm chiming in all the time with comments on links, formatting, etc. :p but
heck, I rather explain it well once on the doc, right !?

The TOC has been somewhat static recently as we've been focusing on adding the actual content.
Maybe it is time for a reality check.

Lets list all the issues we see reported daily, common and not so common. Then we prioritize
them and either add or update the current content of the doc. If we need to redefine some
goals, lets  discuss that here too.

Does that sound fair?

Cheers!
Hernan

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?
> 
> thanks
> david jencks
> 
> 

Mime
View raw message