geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "B.J. Reed" <bjre...@gmail.com>
Subject Re: Geronimo v2.1 documentation
Date Mon, 28 Jan 2008 14:12:48 GMT
Jay D. McHugh wrote:
> 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
>>
>>
>
> If folks think that something like this could work - I would be happy 
> to chip in as a typist.  I took a look at the shell for the 
> documentation and realized that I know far too little to be able to 
> write the docs from scratch.
>
> Plus, it would be useful for me to be able to get more familiar with 
> everything.
>
> Jay
>
>
Hernan,  Since I'm very new to Geronimo development, this would probably 
be a good place for me to get involved and see how things really work.  
Just let me know what I can help you out with.

-- B.J.

Mime
View raw message