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
