I'm really open to new ideas but I don't think phone calls will address this
issue. If we want to catch up with the rest and have a decent documentation we
all need to participate. I mean, we have not been too successful in having a
documentation based discussion on the list, even about what topics to cover
(just see this tread alone).
What I think it would work best is to first chime in for the topics and structure
discussion. Get to an agreement on what are the things that have changed from
previous releases and what are the things the users need the most. We can break
those topics into individual discussion threads on dev@ and use that as a reference
for starting each doc. Or we can draft the content right there on the email, give
it some shape and then we move it to the wiki and do the final fit & finish.
I don't want to rule out the phone calls, a holler may work for some cases, but
in general I think the discussion over the dev@ would work best.
PS. I'm willing to do, besides some of the classic writing ;-) , the formatting
and editing and taking the bullet for any pain related to putting the content
into the wiki. So, let's start with a brain dump, don't worry about the styling
or super refining the content. This would be a great start, we'll take it from
there.
Cheers!
Hernan
Kevan Miller wrote:
On Jan 25, 2008, at 11:22 AM, Hernan Cunico wrote:
Guys, I've been trying to get your attention around Geronimo 2.1
documentation since October last year.
Apache Geronimo is as good as you can communicate it to the users. How
do you expect the users to know all the beeps and whistles? Not a best
way to tell the users HOW TO do things in Geronimo than by having a
good documentation.
How much of your time it would actually take to write up a page
describing a component or module and how to use it? It's you writing
the code, why not you writing about that code and how to use it!?
There are tons of questions on the user@ and dev@ lists about how to
perform basic (and some times not so basic) tasks and configurations,
we get these all the time. This is a clear sign that we need to
improve the way we document the things.
For 2.1 the situation is even worse, we pretty much don't have any
documentation and we can't continue developing documentation the way
we've been doing in the past. The way it looks now, Geronimo 2.1 won't
have supporting documentation.
Let's discuss here what areas need to be covered and who can work on
documenting them. It is your turn now.
Hernan,
I hear your pain. And totally agree that good docs will make things much
easier for our users (as well as ourselves).
I know I'm as guilty (perhaps more so) as anyone else at failing to help
pitch in. Everybody's pretty busy. Also, there's a definite tendency for
skilled developers to be, well, skilled *developers*.
Perhaps there are some alternate ways to help this process go faster? I
wonder if it would be easier for people to discuss a particular topic
with you on a phone call? Hopefully providing enough information for you
to transform into flowery prose and lucid illustrations? If we want, we
could make this a conference call (so interested parties could join).
I don't think this technique can work for all docs. We can't expect you
to write everything. However, it might help kickstart the process in
some critical sections...
--kevan
