Re: Geronimo v2.1 documentation status

[Shiva Kumar H R]

:-) Good news.

On Tue, Mar 4, 2008 at 4:05 AM, Hernan Cunico <[EMAIL PROTECTED]> wrote:

> Hi All,
> I'm normally the one making the requests for contributions to the doc,
> asking for your help and usually not too happy with the content we end up
> having.
>
> Well, today it's a totally different scenario. I wanted to truly thank all
> of you contributing to the project's documentation. There is a great deal of
> documents being created/updated daily, to the point where it's hard to catch
> up with the updates. Ain't that great !? ;-)
>
> In fact, given the volume and that we are not using JIRA for tracking docs
> ( and no, that was not a proposal ;-) ), we had to come up with some
> alternative ways to keep track of what we do so we don't overlap. We
> implemented a few tables on the 2.1 doc itself for identifying content
> being moved from 2.0 as well as what new content was being developed. We
> have another table on the Dev space that give us a perspective of what
> topics we have been covering throughout all Geronimo releases.
>
> We are not quite out of the bushes yet but, oh boy, we did come a very
> long way from 2.0 doc and I wanted to take a min and thank everybody
> working on the doc.
>
>http://cwiki.apache.org/GMOxDOC21/ is truly a community effort. Great
> work everyone, lets keep it coming!
>
> And as usual comments, ideas and more contributions are very welcome !!! (
> I couldn't resist ;-) )
>
> Cheers!
> Hernan
>



-- 
Thanks,
Shiva

Re: Geronimo v2.1 documentation update

[Vamsavardhana Reddy]

On Sat, Feb 23, 2008 at 1:12 AM, Hernan Cunico <[EMAIL PROTECTED]> wrote:

> "Need update" would be something like moved the content from prev release
> but not yet finished. Or worked on some brand new content but still need to
> update it to reflect the latest changes on the server ( think of it as if
> you started before Geronimo was released, then you would have a bunch of
> SNAPSHOTs all over the place).
> If there is anything on the Need update column then there should not be a
> green check mark on the status column. Does this make sense? what do others
> think?

I started using that column like a "comments" column which will let me know
what & why the update is needed.  Otherwise it will just be a complement of
the status column.



>
> As for "...still needs someone who knows what the article is talking about
> to update..." I would hope that the people who jumps into any of those
> subjects can follow it through all the way. Otherwise this table won't help
> us figure out how complete the content really is.
>
> Cheers!
> Hernan
>
> Jason Warner wrote:
> > Hernan,
> >
> > What's the "need update" column for on the 2.0 Update status page?  Is
> > that to mark a page that is moved over but still needs someone who knows
> > what the article is talking about to update it based on 2.1?
> >
> >
> > On Thu, Feb 21, 2008 at 5:04 PM, Hernan Cunico <[EMAIL PROTECTED]
> > > wrote:
> >
> > Hi All,
> > an interesting thing happened twice already this week. Given the
> > number of doc contributions that started to flow recently (THANKS TO
> > ALL OF YOU CONTRIBUTING) we ended up having, or just about to have,
> > some overlapping.
> >
> > Talking with some of the folks we thought it would be a good idea to
> > put together some sort of table or a list with the topics and who
> > was working on them. So, I updated the 2.1 doc home page and added a
> > few more pages to help us figure out who is working on what. This
> > should also help bring in new contributions.
> >
> >
> > Here is the page, I already started to put some names there. Pls
> > chime in and update the info with the content you are working on.
> >
> > http://cwiki.apache.org/GMOxDOC21/documentation-development.html
> >
> > What to others think?
> >
> > Cheers!
> > Hernan
> >
> >
> >
> >
> > --
> > ~Jason Warner
>

Re: Geronimo v2.1 documentation update

[Hernan Cunico]

Jason Warner wrote:



On Fri, Feb 22, 2008 at 3:15 PM, Hernan Cunico <[EMAIL PROTECTED] 
> wrote:




Jason Warner wrote:
 >
 >
 > On Fri, Feb 22, 2008 at 2:42 PM, Hernan Cunico <[EMAIL PROTECTED]

 > >> wrote:
 >
 > "Need update" would be something like moved the content from prev
 > release but not yet finished. Or worked on some brand new content
 > but still need to update it to reflect the latest changes on the
 > server ( think of it as if you started before Geronimo was
released,
 > then you would have a bunch of SNAPSHOTs all over the place).
 > If there is anything on the Need update column then there
should not
 > be a green check mark on the status column. Does this make sense?
 > what do others think?
 >
 >
 > Your explanation of "Need update" seems to be about what I thought it
 > was.  Thanks for the clarification.
 >
 >
 > As for "...still needs someone who knows what the article is
talking
 > about to update..." I would hope that the people who jumps
into any
 > of those subjects can follow it through all the way.
Otherwise this
 > table won't help us figure out how complete the content
really is.
 >
 >
 >  I understand your concern, but there are many topics in the 2.0
 > documentation that are large and fairly encompassing.  I don't
think it
 > unreasonable for someone to move the document over and fix what
they're
 > able to, but then mark it as Need update if they're not
comfortable with
 > their knowledge on a certain subject.  I think it'll be very
difficult
 > to port all this documentation over if we wait for someone who's
able to
 > verify every thing on a page to take responsibility for it.  I'm not
 > advocating people just blindly port pages over and mark it as Need
 > update without attempting to verify what they can.  I just don't want
 > people to be turned off from helping with documentation just because
 > they're not a power user.
 >

So, how do we keep track of such topics then. I think looking into
previous docs and updating the content is a great start for those
that are not experts.

By following through I mean just that, if you don't know the
entirely topic bring the question forward (dev@, IRC, jira, phone,
smoke signals, anything that works) What a best way to learn a new
topic than following it through from start to end. I find this very
encouraging :D

Cheers!
Hernan


Ok, I see what you're saying now.  I was misunderstanding the point you 
were trying to convey.  I thought you were implying that people new to 
geronimo should avoid helping with documentation until they've become 
proficient whereas you were actually saying the exact opposite.  My 
apologies.




uhh, no idea my message could have been interpreted that way. Maybe I need 
to read what I write more in detail :P

Actually, new users get to see things we sometimes overlook or give as granted.


Cheers!
Hernan



 >
 >
 > Cheers!
 > Hernan
 >
 > Jason Warner wrote:
 >  > Hernan,
 >  >
 >  > What's the "need update" column for on the 2.0 Update status
 > page?  Is
 >  > that to mark a page that is moved over but still needs someone
 > who knows
 >  > what the article is talking about to update it based on 2.1?
 >  >
 >  >
 >  > On Thu, Feb 21, 2008 at 5:04 PM, Hernan Cunico
<[EMAIL PROTECTED] 
 > >
 >  > 
  >
 >  > Hi All,
 >  > an interesting thing happened twice already this week.
Given the
 >  > number of doc contributions that started to flow recently
 > (THANKS TO
 >  > ALL OF YOU CONTRIBUTING) we ended up having, or just
about to
 > have,
 >  > some overlapping.
 >  >
 >  > Talking with some of the folks we thought it would be
a good
 > idea to
 >  > put together some sort of table or a list with the
topics and who
 >  > was working on them. So, I updated the 2.1 doc home
page and
 > added a
 >  > few more pages to help us figure out who is working on
what. This
 >  > should also help bring in new contributions.
 >  >
 >  >
 >  > Here is the page, I already started to put some names
there. Pls
 >  > chime in and update the info with the content yo

Re: Geronimo v2.1 documentation update

[Jason Warner]

On Fri, Feb 22, 2008 at 3:15 PM, Hernan Cunico <[EMAIL PROTECTED]> wrote:

>
>
> Jason Warner wrote:
> >
> >
> > On Fri, Feb 22, 2008 at 2:42 PM, Hernan Cunico <[EMAIL PROTECTED]
> > > wrote:
> >
> > "Need update" would be something like moved the content from prev
> > release but not yet finished. Or worked on some brand new content
> > but still need to update it to reflect the latest changes on the
> > server ( think of it as if you started before Geronimo was released,
> > then you would have a bunch of SNAPSHOTs all over the place).
> > If there is anything on the Need update column then there should not
> > be a green check mark on the status column. Does this make sense?
> > what do others think?
> >
> >
> > Your explanation of "Need update" seems to be about what I thought it
> > was.  Thanks for the clarification.
> >
> >
> > As for "...still needs someone who knows what the article is talking
> > about to update..." I would hope that the people who jumps into any
> > of those subjects can follow it through all the way. Otherwise this
> > table won't help us figure out how complete the content really is.
> >
> >
> >  I understand your concern, but there are many topics in the 2.0
> > documentation that are large and fairly encompassing.  I don't think it
> > unreasonable for someone to move the document over and fix what they're
> > able to, but then mark it as Need update if they're not comfortable with
> > their knowledge on a certain subject.  I think it'll be very difficult
> > to port all this documentation over if we wait for someone who's able to
> > verify every thing on a page to take responsibility for it.  I'm not
> > advocating people just blindly port pages over and mark it as Need
> > update without attempting to verify what they can.  I just don't want
> > people to be turned off from helping with documentation just because
> > they're not a power user.
> >
>
> So, how do we keep track of such topics then. I think looking into
> previous docs and updating the content is a great start for those that are
> not experts.
>
> By following through I mean just that, if you don't know the entirely
> topic bring the question forward (dev@, IRC, jira, phone, smoke signals,
> anything that works) What a best way to learn a new topic than following it
> through from start to end. I find this very encouraging :D
>
> Cheers!
> Hernan
>

Ok, I see what you're saying now.  I was misunderstanding the point you were
trying to convey.  I thought you were implying that people new to geronimo
should avoid helping with documentation until they've become proficient
whereas you were actually saying the exact opposite.  My apologies.

>
> >
> >
> > Cheers!
> > Hernan
> >
> > Jason Warner wrote:
> >  > Hernan,
> >  >
> >  > What's the "need update" column for on the 2.0 Update status
> > page?  Is
> >  > that to mark a page that is moved over but still needs someone
> > who knows
> >  > what the article is talking about to update it based on 2.1?
> >  >
> >  >
> >  > On Thu, Feb 21, 2008 at 5:04 PM, Hernan Cunico <[EMAIL PROTECTED]
> > 
> >  > >> wrote:
> >  >
> >  > Hi All,
> >  > an interesting thing happened twice already this week. Given
> the
> >  > number of doc contributions that started to flow recently
> > (THANKS TO
> >  > ALL OF YOU CONTRIBUTING) we ended up having, or just about to
> > have,
> >  > some overlapping.
> >  >
> >  > Talking with some of the folks we thought it would be a good
> > idea to
> >  > put together some sort of table or a list with the topics and
> who
> >  > was working on them. So, I updated the 2.1 doc home page and
> > added a
> >  > few more pages to help us figure out who is working on what.
> This
> >  > should also help bring in new contributions.
> >  >
> >  >
> >  > Here is the page, I already started to put some names there.
> Pls
> >  > chime in and update the info with the content you are working
> on.
> >  >
> >  >
> http://cwiki.apache.org/GMOxDOC21/documentation-development.html
> >  >
> >  > What to others think?
> >  >
> >  > Cheers!
> >  > Hernan
> >  >
> >  >
> >  >
> >  >
> >  > --
> >  > ~Jason Warner
> >
> >
> >
> >
> > --
> > ~Jason Warner
>



-- 
~Jason Warner

Re: Geronimo v2.1 documentation update

[Hernan Cunico]

Jason Warner wrote:



On Fri, Feb 22, 2008 at 2:42 PM, Hernan Cunico <[EMAIL PROTECTED] 
> wrote:


"Need update" would be something like moved the content from prev
release but not yet finished. Or worked on some brand new content
but still need to update it to reflect the latest changes on the
server ( think of it as if you started before Geronimo was released,
then you would have a bunch of SNAPSHOTs all over the place).
If there is anything on the Need update column then there should not
be a green check mark on the status column. Does this make sense?
what do others think?

 
Your explanation of "Need update" seems to be about what I thought it 
was.  Thanks for the clarification.  



As for "...still needs someone who knows what the article is talking
about to update..." I would hope that the people who jumps into any
of those subjects can follow it through all the way. Otherwise this
table won't help us figure out how complete the content really is.


 I understand your concern, but there are many topics in the 2.0 
documentation that are large and fairly encompassing.  I don't think it 
unreasonable for someone to move the document over and fix what they're 
able to, but then mark it as Need update if they're not comfortable with 
their knowledge on a certain subject.  I think it'll be very difficult 
to port all this documentation over if we wait for someone who's able to 
verify every thing on a page to take responsibility for it.  I'm not 
advocating people just blindly port pages over and mark it as Need 
update without attempting to verify what they can.  I just don't want 
people to be turned off from helping with documentation just because 
they're not a power user.




So, how do we keep track of such topics then. I think looking into previous 
docs and updating the content is a great start for those that are not experts.

By following through I mean just that, if you don't know the entirely topic 
bring the question forward (dev@, IRC, jira, phone, smoke signals, anything 
that works) What a best way to learn a new topic than following it through from 
start to end. I find this very encouraging :D

Cheers!
Hernan




Cheers!
Hernan

Jason Warner wrote:
 > Hernan,
 >
 > What's the "need update" column for on the 2.0 Update status
page?  Is
 > that to mark a page that is moved over but still needs someone
who knows
 > what the article is talking about to update it based on 2.1?
 >
 >
 > On Thu, Feb 21, 2008 at 5:04 PM, Hernan Cunico <[EMAIL PROTECTED]

 > >> wrote:
 >
 > Hi All,
 > an interesting thing happened twice already this week. Given the
 > number of doc contributions that started to flow recently
(THANKS TO
 > ALL OF YOU CONTRIBUTING) we ended up having, or just about to
have,
 > some overlapping.
 >
 > Talking with some of the folks we thought it would be a good
idea to
 > put together some sort of table or a list with the topics and who
 > was working on them. So, I updated the 2.1 doc home page and
added a
 > few more pages to help us figure out who is working on what. This
 > should also help bring in new contributions.
 >
 >
 > Here is the page, I already started to put some names there. Pls
 > chime in and update the info with the content you are working on.
 >
 > http://cwiki.apache.org/GMOxDOC21/documentation-development.html
 >
 > What to others think?
 >
 > Cheers!
 > Hernan
 >
 >
 >
 >
 > --
 > ~Jason Warner




--
~Jason Warner

Re: Geronimo v2.1 documentation update

[Hernan Cunico]

Guys, that TOC is not casted in stone. That was my way to put some ideas 
together for topics to cover.

IIRC, there have been discussion threads started back in October/November last 
year to gather input around 2.1 documentation

Back to the tables, I rather have more column there than I actually need. 
Although I like Confluence dealing with tables is a royal PITA.

Maybe having just Topic, owner, status would do the trick. If we are all OK 
with that then we just remove the titles and done deal.

Cheers!
Hernan

Joseph Leong wrote:
I'm glad the question has been brought up, i was wondering myself... 
Ditto above 

Also, for the sections that are in 2.0 users that are not on 2.1 users - 
does this mean we have decided to not transfer these sections over? 
(i.e. some of the sample applications) or is it because some of the 
documentation outline for 2.1 is not complete yet.


Wishing you all the best,
Joseph Leong

On Fri, Feb 22, 2008 at 2:09 PM, Dan Becker <[EMAIL PROTECTED] 
> wrote:


Jason Warner wrote:
 > What's the "need update" column for on the 2.0 Update status
page?  Is that
 > to mark a page that is moved over but still needs someone who
knows what the
 > article is talking about to update it based on 2.1?

Good question. I've been treating it as "needs rework to move to 2.1"
for planning purposes, but I agree this column can have many meanings.
An official statement would be helpful.
--
Thanks, Dan Becker
email: mailto://[EMAIL PROTECTED]

Re: Geronimo v2.1 documentation update

[Jason Warner]

On Fri, Feb 22, 2008 at 2:42 PM, Hernan Cunico <[EMAIL PROTECTED]> wrote:

> "Need update" would be something like moved the content from prev release
> but not yet finished. Or worked on some brand new content but still need to
> update it to reflect the latest changes on the server ( think of it as if
> you started before Geronimo was released, then you would have a bunch of
> SNAPSHOTs all over the place).
> If there is anything on the Need update column then there should not be a
> green check mark on the status column. Does this make sense? what do others
> think?


Your explanation of "Need update" seems to be about what I thought it was.
Thanks for the clarification.

>
> As for "...still needs someone who knows what the article is talking about
> to update..." I would hope that the people who jumps into any of those
> subjects can follow it through all the way. Otherwise this table won't help
> us figure out how complete the content really is.
>

 I understand your concern, but there are many topics in the
2.0documentation that are large and fairly encompassing.  I don't
think it
unreasonable for someone to move the document over and fix what they're able
to, but then mark it as Need update if they're not comfortable with their
knowledge on a certain subject.  I think it'll be very difficult to port all
this documentation over if we wait for someone who's able to verify every
thing on a page to take responsibility for it.  I'm not advocating people
just blindly port pages over and mark it as Need update without attempting
to verify what they can.  I just don't want people to be turned off from
helping with documentation just because they're not a power user.



> Cheers!
> Hernan
>
> Jason Warner wrote:
> > Hernan,
> >
> > What's the "need update" column for on the 2.0 Update status page?  Is
> > that to mark a page that is moved over but still needs someone who knows
> > what the article is talking about to update it based on 2.1?
> >
> >
> > On Thu, Feb 21, 2008 at 5:04 PM, Hernan Cunico <[EMAIL PROTECTED]
> > > wrote:
> >
> > Hi All,
> > an interesting thing happened twice already this week. Given the
> > number of doc contributions that started to flow recently (THANKS TO
> > ALL OF YOU CONTRIBUTING) we ended up having, or just about to have,
> > some overlapping.
> >
> > Talking with some of the folks we thought it would be a good idea to
> > put together some sort of table or a list with the topics and who
> > was working on them. So, I updated the 2.1 doc home page and added a
> > few more pages to help us figure out who is working on what. This
> > should also help bring in new contributions.
> >
> >
> > Here is the page, I already started to put some names there. Pls
> > chime in and update the info with the content you are working on.
> >
> > http://cwiki.apache.org/GMOxDOC21/documentation-development.html
> >
> > What to others think?
> >
> > Cheers!
> > Hernan
> >
> >
> >
> >
> > --
> > ~Jason Warner
>



-- 
~Jason Warner

Re: Geronimo v2.1 documentation update

[Hernan Cunico]

"Need update" would be something like moved the content from prev release but not yet finished. Or worked on some brand new content but still need to update it to reflect the latest changes on the server ( think of it as if you started before Geronimo was released, then you would have a bunch of SNAPSHOTs all over the place). 
If there is anything on the Need update column then there should not be a green check mark on the status column. Does this make sense? what do others think?


As for "...still needs someone who knows what the article is talking about to 
update..." I would hope that the people who jumps into any of those subjects can 
follow it through all the way. Otherwise this table won't help us figure out how complete 
the content really is.

Cheers!
Hernan

Jason Warner wrote:

Hernan,

What's the "need update" column for on the 2.0 Update status page?  Is 
that to mark a page that is moved over but still needs someone who knows 
what the article is talking about to update it based on 2.1?



On Thu, Feb 21, 2008 at 5:04 PM, Hernan Cunico <[EMAIL PROTECTED] 
> wrote:


Hi All,
an interesting thing happened twice already this week. Given the
number of doc contributions that started to flow recently (THANKS TO
ALL OF YOU CONTRIBUTING) we ended up having, or just about to have,
some overlapping.

Talking with some of the folks we thought it would be a good idea to
put together some sort of table or a list with the topics and who
was working on them. So, I updated the 2.1 doc home page and added a
few more pages to help us figure out who is working on what. This
should also help bring in new contributions.


Here is the page, I already started to put some names there. Pls
chime in and update the info with the content you are working on.

http://cwiki.apache.org/GMOxDOC21/documentation-development.html

What to others think?

Cheers!
Hernan




--
~Jason Warner

Re: Geronimo v2.1 documentation update

[Joseph Leong]

I'm glad the question has been brought up, i was wondering myself... Ditto
above

Also, for the sections that are in 2.0 users that are not on 2.1 users -
does this mean we have decided to not transfer these sections over? (i.e.
some of the sample applications) or is it because some of the documentation
outline for 2.1 is not complete yet.

Wishing you all the best,
Joseph Leong

On Fri, Feb 22, 2008 at 2:09 PM, Dan Becker <[EMAIL PROTECTED]> wrote:

> Jason Warner wrote:
> > What's the "need update" column for on the 2.0 Update status page?  Is
> that
> > to mark a page that is moved over but still needs someone who knows what
> the
> > article is talking about to update it based on 2.1?
>
> Good question. I've been treating it as "needs rework to move to 2.1"
> for planning purposes, but I agree this column can have many meanings.
> An official statement would be helpful.
> --
> Thanks, Dan Becker
> email: mailto://[EMAIL PROTECTED]
>

Re: Geronimo v2.1 documentation update

[Dan Becker]

Jason Warner wrote:

What's the "need update" column for on the 2.0 Update status page?  Is that
to mark a page that is moved over but still needs someone who knows what the
article is talking about to update it based on 2.1?


Good question. I've been treating it as "needs rework to move to 2.1" 
for planning purposes, but I agree this column can have many meanings. 
An official statement would be helpful.

--
Thanks, Dan Becker
email: mailto://[EMAIL PROTECTED]

Re: Geronimo v2.1 documentation update

[Jason Warner]

Hernan,

What's the "need update" column for on the 2.0 Update status page?  Is that
to mark a page that is moved over but still needs someone who knows what the
article is talking about to update it based on 2.1?


On Thu, Feb 21, 2008 at 5:04 PM, Hernan Cunico <[EMAIL PROTECTED]> wrote:

> Hi All,
> an interesting thing happened twice already this week. Given the number of
> doc contributions that started to flow recently (THANKS TO ALL OF YOU
> CONTRIBUTING) we ended up having, or just about to have, some overlapping.
>
> Talking with some of the folks we thought it would be a good idea to put
> together some sort of table or a list with the topics and who was working on
> them. So, I updated the 2.1 doc home page and added a few more pages to
> help us figure out who is working on what. This should also help bring in
> new contributions.
>
>
> Here is the page, I already started to put some names there. Pls chime in
> and update the info with the content you are working on.
>
> http://cwiki.apache.org/GMOxDOC21/documentation-development.html
>
> What to others think?
>
> Cheers!
> Hernan
>



-- 
~Jason Warner

Re: Geronimo v2.1 documentation

[Hernan Cunico]

Hey Kevan,
It's OK to have some overlap between the release notes and the rest of the 
wiki. We currently ship only the rel notes with the product, not the product 
doc (wiki)

Most of the content on the rel notes should be based on the "what's new" 
section. However that section is currently empty so we'll have to the other way around 
and build that up from what we have in the release notes.

One thing I tried to do in the past but didn't pick up in popularity was to 
have most of the release notes generated automatically. I mean you would work 
some content out directly on the appropriate sections in the wiki and then the 
release notes pulls in and builds up dynamically  from that content. We would 
just do some minor touch ups here and there. I think going this way is best as 
will also foster greater level of contributions to the documentation.

Cheers!
Hernan

Kevan Miller wrote:
Unless somebody is already working on it, I'm going to start updating 
the RELEASE_NOTES -- 
http://cwiki.apache.org/GMOxDOC21/release-notes-21txt.html


I'm noticing that the release notes have a good deal of overlap with the 
README and other wiki documentation. I also see that we're not including 
the README in our binary distributions. The README contains the "notice 
regarding cryptographic software" -- this needs to be included in our 
distribution.


I'm going to whittle down the RELEASE_NOTES to focus on specific 
features of the current release. I'll update the README with current 
information, and will make sure we're including the README in our 
distributions.


--kevan

Re: Geronimo v2.1 documentation

[Kevan Miller]

Unless somebody is already working on it, I'm going to start updating  
the RELEASE_NOTES -- http://cwiki.apache.org/GMOxDOC21/release-notes-21txt.html


I'm noticing that the release notes have a good deal of overlap with  
the README and other wiki documentation. I also see that we're not  
including the README in our binary distributions. The README contains  
the "notice regarding cryptographic software" -- this needs to be  
included in our distribution.


I'm going to whittle down the RELEASE_NOTES to focus on specific  
features of the current release. I'll update the README with current  
information, and will make sure we're including the README in our  
distributions.


--kevan

Re: Geronimo v2.1 documentation

[Hernan Cunico]

Hi Ashish,
this is great news !!! Thanks for your interest in contributing to the project 
documentation.

Documenting these topics will certainly help addressing some of the usability 
issues.

Welcome aboard!

Cheers!
Hernan

Ashish Jain wrote:

Hi,
I have prepared following list of tutorials *(developer guide)* items. 
Initial task will  be two work on two items from each bullet. This will 
enable to cover most of the topics initially and later the concentration 
will be on increasing the count of articles in each category.


Each article will start with basics of each API used and later step by 
step explanation of the application development. This will enable the 
developers to find all the information and references at one place. This 
will in turn help to improve the Usability and Consumabiltiy of Geronimo.


The timeframe for the complete list will be around 6 months considering 
the fact that it involves quite a good amount of learning. Although the 
initial task will be to complete 2 articles in each category.


The environment will be AG 2.1, GEP 2.1, WTP 2.0.1, Eclipse 3.3 SDK and 
Windows XP.


The list is as follows:

*Java Server Faces*
Developing a web application with JSF.
AJAX with JSF.
Using JSP Immediate Expressions to access JSF.
UI development with JSF.
JSF application that created, deletes, update and delete operations 
against database ttables.


*Web Application*
   Web application for JMS access.
   Web Application for EJB access.
   Web Application for JDBC access.

*Application Client*
Application client  accessing EJB.

*Web Services*
Building JAX-WS pojo web service
Building JAX-WS EJB stateless session bean web services.
RESTFUL Web Services
SAAJ Web Services
MTOM Web Services
WS Addressing.

*Annotations*
JAX-WS web service and client using annotations.


*Java Persistence API*
Using Java Persistence API in application client.
Working with JSF and JPA.

*EJB*
Stateless Session Bean
Stateful Session Bean
Message Driven Bean.
Container Managed Persistence with JPA
Bean Managed Persistence with JPA

Regarding Portlets, Geronimo extensions there is still more info that 
needs to be collected.


Please provide you comments and suggestions.

Thanks
Ashish

On Feb 7, 2008 12:44 AM, Hernan Cunico <[EMAIL PROTECTED] 
> wrote:


Donald Woods wrote:
 > The TOC seems to be too Feature centric.
 > As new users pickup Geronimo, we really need to focus on making their
 > startup/learning curve as short and simple as possible.
 >
 > How about grouping the content based on its intended audience with
 > cross-links between sections as needed -
 >
 > * Getting Started
 > ** What's New/Changes from 2.0
 > ** Obtaining, Community Support, Opening JIRAs
 > ** Using GShell
 >
 > * Developers
 > ** Deployment plan creator
 > ** Schema Docs (XSD to JavaDoc/HTML)
 > ** Migrating apps from prior releases
 > ** Pluggable Console
 > ** Plugin Infrastructure
 > ** Eclipse Plugin
 > ** Sample Apps
 >
 > * Administrators
 > ** Configuration
 > ** Administration Console
 > ** Security and LoginModule usage
 > ** Resource Adapters (DB, JMS, ...)
 > ** Server Instances/Custom Assemblies
 > ** Clustering
 > ** Monitoring
 > ** Advanced GShell topics
 >

Yup, checking the latest updates it seems like we are heading in
that direction.

 > The ReleaseNotes are included in the assemblies, so no need to
duplicate

We generate the release notes from the wiki so we can keep them here
or move the file to maybe GMOxPMGT space.

 > it in the docs.  Anything on building from source or debuging a
server
 > in Eclipse should be kept in the GMOxDev wiki.

GMOxDev has lot of info and not all up to date. It wouldn't hurt to
have the 2.1 specific build info under GMOxDOC21. I mean, the more
the merrier

 >
 > Also, now that we have a start of a internationalized Admin
Console, I'd
 > keep the number of screen shots to a minimum, as to reduce the effort
 > required for others wanting to translate the docs into other
languages.

Agreed, screen captures will become an issue, even for updating
future releases. It's just that some times a screen shot saves you a
lot of typing.

Good comments, keep it coming !

Cheers!
Hernan

 >
 >
 > -Donald
 >
 > Hernan Cunico wrote:
 >> Hi All,
 >> some time ago I started to put together some topics for Geronimo
v2.1
 >> documentation.
 >> I tried to focus on the biggest new things we are offering now,
topics
 >> we didn't have before and now we need to start from scratch.
 >>
 >> The Geronimo v2.1 documentation space is already available here
 >> http://cwiki.apache.org/GMOxD

Re: Geronimo v2.1 documentation

[Ashish Jain]

Hi,
I have prepared following list of tutorials *(developer guide)* items.
Initial task will  be two work on two items from each bullet. This will
enable to cover most of the topics initially and later the concentration
will be on increasing the count of articles in each category.

Each article will start with basics of each API used and later step by step
explanation of the application development. This will enable the developers
to find all the information and references at one place. This will in turn
help to improve the Usability and Consumabiltiy of Geronimo.

The timeframe for the complete list will be around 6 months considering the
fact that it involves quite a good amount of learning. Although the initial
task will be to complete 2 articles in each category.

The environment will be AG 2.1, GEP 2.1, WTP 2.0.1, Eclipse 3.3 SDK and
Windows XP.

The list is as follows:

*Java Server Faces*
Developing a web application with JSF.
AJAX with JSF.
Using JSP Immediate Expressions to access JSF.
UI development with JSF.
JSF application that created, deletes, update and delete operations
against database ttables.

*Web Application*
   Web application for JMS access.
   Web Application for EJB access.
   Web Application for JDBC access.

*Application Client*
Application client  accessing EJB.

*Web Services*
Building JAX-WS pojo web service
Building JAX-WS EJB stateless session bean web services.
RESTFUL Web Services
SAAJ Web Services
MTOM Web Services
WS Addressing.

*Annotations*
JAX-WS web service and client using annotations.


*Java Persistence API*
Using Java Persistence API in application client.
Working with JSF and JPA.

*EJB*
Stateless Session Bean
Stateful Session Bean
Message Driven Bean.
Container Managed Persistence with JPA
Bean Managed Persistence with JPA

Regarding Portlets, Geronimo extensions there is still more info that needs
to be collected.

Please provide you comments and suggestions.

Thanks
Ashish

On Feb 7, 2008 12:44 AM, Hernan Cunico <[EMAIL PROTECTED]> wrote:

> Donald Woods wrote:
> > The TOC seems to be too Feature centric.
> > As new users pickup Geronimo, we really need to focus on making their
> > startup/learning curve as short and simple as possible.
> >
> > How about grouping the content based on its intended audience with
> > cross-links between sections as needed -
> >
> > * Getting Started
> > ** What's New/Changes from 2.0
> > ** Obtaining, Community Support, Opening JIRAs
> > ** Using GShell
> >
> > * Developers
> > ** Deployment plan creator
> > ** Schema Docs (XSD to JavaDoc/HTML)
> > ** Migrating apps from prior releases
> > ** Pluggable Console
> > ** Plugin Infrastructure
> > ** Eclipse Plugin
> > ** Sample Apps
> >
> > * Administrators
> > ** Configuration
> > ** Administration Console
> > ** Security and LoginModule usage
> > ** Resource Adapters (DB, JMS, ...)
> > ** Server Instances/Custom Assemblies
> > ** Clustering
> > ** Monitoring
> > ** Advanced GShell topics
> >
>
> Yup, checking the latest updates it seems like we are heading in that
> direction.
>
> > The ReleaseNotes are included in the assemblies, so no need to duplicate
>
> We generate the release notes from the wiki so we can keep them here or
> move the file to maybe GMOxPMGT space.
>
> > it in the docs.  Anything on building from source or debuging a server
> > in Eclipse should be kept in the GMOxDev wiki.
>
> GMOxDev has lot of info and not all up to date. It wouldn't hurt to have
> the 2.1 specific build info under GMOxDOC21. I mean, the more the merrier
>
> >
> > Also, now that we have a start of a internationalized Admin Console, I'd
> > keep the number of screen shots to a minimum, as to reduce the effort
> > required for others wanting to translate the docs into other languages.
>
> Agreed, screen captures will become an issue, even for updating future
> releases. It's just that some times a screen shot saves you a lot of typing.
>
> Good comments, keep it coming !
>
> Cheers!
> Hernan
>
> >
> >
> > -Donald
> >
> > Hernan Cunico wrote:
> >> Hi All,
> >> some time ago I started to put together some topics for Geronimo v2.1
> >> documentation.
> >> I tried to focus on the biggest new things we are offering now, topics
> >> we didn't have before and now we need to start from scratch.
> >>
> >> The Geronimo v2.1 documentation space is already available here
> >> http://cwiki.apache.org/GMOxDOC21/documentation.html
> >>
> >> The initial TOC includes:
> >>
> >> * Configuration changes
> >> * Deployment
> >>  ** Deployment plan creator
> >> * Geronimo Administration Console enhancements
> >> * GShell
> >> * Monitoring
> >> * Pluggable console
> >> * Plugin infrastructure enhancements
> >> * RELEASE-NOTES-2.1.TXT
> >> * Sample applications
> >> * Security
> >> * Tooling
> >> * What's new?
> >>
> >> Each of these pages already contain a few lines with some initial
> >> thoughts. N

Re: Geronimo v2.1 documentation

[Hernan Cunico]

Donald Woods wrote:

The TOC seems to be too Feature centric.
As new users pickup Geronimo, we really need to focus on making their 
startup/learning curve as short and simple as possible.


How about grouping the content based on its intended audience with 
cross-links between sections as needed -


* Getting Started
** What's New/Changes from 2.0
** Obtaining, Community Support, Opening JIRAs
** Using GShell

* Developers
** Deployment plan creator
** Schema Docs (XSD to JavaDoc/HTML)
** Migrating apps from prior releases
** Pluggable Console
** Plugin Infrastructure
** Eclipse Plugin
** Sample Apps

* Administrators
** Configuration
** Administration Console
** Security and LoginModule usage
** Resource Adapters (DB, JMS, ...)
** Server Instances/Custom Assemblies
** Clustering
** Monitoring
** Advanced GShell topics



Yup, checking the latest updates it seems like we are heading in that direction.

The ReleaseNotes are included in the assemblies, so no need to duplicate 


We generate the release notes from the wiki so we can keep them here or move 
the file to maybe GMOxPMGT space.

it in the docs.  Anything on building from source or debuging a server 
in Eclipse should be kept in the GMOxDev wiki.


GMOxDev has lot of info and not all up to date. It wouldn't hurt to have the 
2.1 specific build info under GMOxDOC21. I mean, the more the merrier



Also, now that we have a start of a internationalized Admin Console, I'd 
keep the number of screen shots to a minimum, as to reduce the effort 
required for others wanting to translate the docs into other languages.


Agreed, screen captures will become an issue, even for updating future 
releases. It's just that some times a screen shot saves you a lot of typing.

Good comments, keep it coming !

Cheers!
Hernan




-Donald

Hernan Cunico wrote:

Hi All,
some time ago I started to put together some topics for Geronimo v2.1 
documentation.
I tried to focus on the biggest new things we are offering now, topics 
we didn't have before and now we need to start from scratch.


The Geronimo v2.1 documentation space is already available here 
http://cwiki.apache.org/GMOxDOC21/documentation.html


The initial TOC includes:

* Configuration changes
* Deployment
 ** Deployment plan creator
* Geronimo Administration Console enhancements
* GShell
* Monitoring
* Pluggable console
* Plugin infrastructure enhancements
* RELEASE-NOTES-2.1.TXT
* Sample applications
* Security
* Tooling
* What's new?

Each of these pages already contain a few lines with some initial 
thoughts. Need your input for adding topics to this list as well as 
developing them.
There might be things we already had in 2.0x but we didn't cover it in 
the doc, pls need your comments on that as well.


I think I'm finish covering *Deployment plan creator*, will do a 
refresh later on as new code gets in.


I also created this "place holder" 
http://cwiki.apache.org/GMOxPMGT/geronimo-v21-list-of-functions-status.html 
under *Apache Geronimo Project Management* on the wiki so we can keep 
track there the features we have ready for prime time and those that 
are not so ready ;-)  I could definitively use that info to build up a 
new set of docs, would also help users to see where we are at.


Cheers!
Hernan

Re: Geronimo v2.1 documentation

[Donald Woods]

The TOC seems to be too Feature centric.
As new users pickup Geronimo, we really need to focus on making their 
startup/learning curve as short and simple as possible.


How about grouping the content based on its intended audience with 
cross-links between sections as needed -


* Getting Started
** What's New/Changes from 2.0
** Obtaining, Community Support, Opening JIRAs
** Using GShell

* Developers
** Deployment plan creator
** Schema Docs (XSD to JavaDoc/HTML)
** Migrating apps from prior releases
** Pluggable Console
** Plugin Infrastructure
** Eclipse Plugin
** Sample Apps

* Administrators
** Configuration
** Administration Console
** Security and LoginModule usage
** Resource Adapters (DB, JMS, ...)
** Server Instances/Custom Assemblies
** Clustering
** Monitoring
** Advanced GShell topics

The ReleaseNotes are included in the assemblies, so no need to duplicate 
it in the docs.  Anything on building from source or debuging a server 
in Eclipse should be kept in the GMOxDev wiki.


Also, now that we have a start of a internationalized Admin Console, I'd 
keep the number of screen shots to a minimum, as to reduce the effort 
required for others wanting to translate the docs into other languages.



-Donald

Hernan Cunico wrote:

Hi All,
some time ago I started to put together some topics for Geronimo v2.1 
documentation.
I tried to focus on the biggest new things we are offering now, topics 
we didn't have before and now we need to start from scratch.


The Geronimo v2.1 documentation space is already available here 
http://cwiki.apache.org/GMOxDOC21/documentation.html


The initial TOC includes:

* Configuration changes
* Deployment
 ** Deployment plan creator
* Geronimo Administration Console enhancements
* GShell
* Monitoring
* Pluggable console
* Plugin infrastructure enhancements
* RELEASE-NOTES-2.1.TXT
* Sample applications
* Security
* Tooling
* What's new?

Each of these pages already contain a few lines with some initial 
thoughts. Need your input for adding topics to this list as well as 
developing them.
There might be things we already had in 2.0x but we didn't cover it in 
the doc, pls need your comments on that as well.


I think I'm finish covering *Deployment plan creator*, will do a refresh 
later on as new code gets in.


I also created this "place holder" 
http://cwiki.apache.org/GMOxPMGT/geronimo-v21-list-of-functions-status.html 
under *Apache Geronimo Project Management* on the wiki so we can keep 
track there the features we have ready for prime time and those that are 
not so ready ;-)  I could definitively use that info to build up a new 
set of docs, would also help users to see where we are at.


Cheers!
Hernan



smime.p7s
Description: S/MIME Cryptographic Signature

Re: Geronimo v2.1 documentation

[Hernan Cunico]

David,
I just found the doc you created and updated the home page so it gets reflected.

Sorry for this back and forth, this is temporary.

Thanks for contributing with the doc.

Cheers!
Hernan

Hernan Cunico wrote:

David Jencks wrote:


On Feb 5, 2008, at 4:31 PM, David Jencks wrote:





I also realize I don't know what the intended relationship between 
these pages is and which one I'm supposed to work from and how (or if) to 


It should not really matter from which page you start. We have two pages 
with the same content because one (index) is the default landing page 
but actually does not have content of its own. Index only has one line 
macro to include the content of Documentation -> {include:Documentation}


So why we have a second page? I just wanted to have "Documentation" 
listed on the breadcrumbs as well as made more sense all the documents 
hierarchically organized "hanging" from a Documentation parent page [ 
Home > Apache Geronimo v2.1 > Documentation ]
It's just a small detail but I think it makes the overall documentation 
looks better. Downside, we have two pages displaying the same content 
and an autoexport plugin that some times is not that "auto".


affect the *documentation.html page.   A few days ago I wrote up info 
on a new jndi feature which shows up fine on the / page but not the 
documentation.html.


For now, the Documentation page is mostly generated by hand. Most of the 
work on the proposed TOC is just that, to list and discuss what contents 
to cover instead of just start creating the pages in some particular 
order. As we start to fill the documentation with content I'll start to 
mix in the Documentation page some macros to automatically generate 
links to some sections.


Where did you put that doc? it's probably just matter of changing the 
parent page.


Just in case, here is a doc for how the documentation is organized 
within the different spaces in Confluence. 
http://cwiki.apache.org/geronimo/geronimo-cwiki-documentation-architecture.html 



Cheers!
Hernan





thanks
david jencks



...

Re: Geronimo v2.1 documentation

[Hernan Cunico]

David Jencks wrote:


On Feb 5, 2008, at 4:31 PM, David Jencks wrote:





I also realize I don't know what the intended relationship between these 
pages is and which one I'm supposed to work from and how (or if) to 


It should not really matter from which page you start. We have two pages with the 
same content because one (index) is the default landing page but actually does not 
have content of its own. Index only has one line macro to include the content of 
Documentation -> {include:Documentation}

So why we have a second page? I just wanted to have "Documentation" listed on the breadcrumbs as well as made more sense all the documents hierarchically organized "hanging" from a Documentation parent page [ Home > Apache Geronimo v2.1 > Documentation ] 


It's just a small detail but I think it makes the overall documentation looks better. 
Downside, we have two pages displaying the same content and an autoexport plugin that 
some times is not that "auto".

affect the *documentation.html page.   A few days ago I wrote up info on 
a new jndi feature which shows up fine on the / page but not the 
documentation.html.


For now, the Documentation page is mostly generated by hand. Most of the work 
on the proposed TOC is just that, to list and discuss what contents to cover 
instead of just start creating the pages in some particular order. As we start 
to fill the documentation with content I'll start to mix in the Documentation 
page some macros to automatically generate links to some sections.

Where did you put that doc? it's probably just matter of changing the parent 
page.

Just in case, here is a doc for how the documentation is organized within the different spaces in Confluence. 
http://cwiki.apache.org/geronimo/geronimo-cwiki-documentation-architecture.html


Cheers!
Hernan





thanks
david jencks



...

Re: Geronimo v2.1 documentation

[Hernan Cunico]

David Jencks wrote:
Would it be possible to link to the in-progress 2.1 documentation from 
what I think is the main docs 
page http://geronimo.apache.org/documentation.html?


Done! it should get reflected within the next hour or so.



I'm also wondering whether there is some way to make the existence of 


http://cwiki.apache.org/GMOxDOC21/documentation.html

more obvious from 


http://cwiki.apache.org/GMOxDOC21/

which seems to be what I always find when I look for the 2.1 docs.


I just fixed this, it was caused by caused by a limitation in the autoexport plugin we use. 
index.html and documentation.html should display the same information, "index" actually does an include of "documentation"




Are there plans to copy the parts of the 1.x and 2.0.x docs that are 
still relevant to the 2.1 docs?  I think this did not happen completely 
for the 1.1 >> 2.0 release.


There are plans for a lot more than that ;-) 
I always try to carry over the parts that are still relevant and update them as needed. There is a lot of fish to fry so it would be great if we can all chip into the doc. At least from time to time ;-)


Cheers!
Hernan



thanks
david jencks


On Jan 25, 2008, at 8: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.


Cheers!
Hernan

Kevan Miller wrote:

On Jan 10, 2008, at 5:14 PM, Hernan Cunico wrote:

Hi All,
some time ago I started to put together some topics for Geronimo 
v2.1 documentation.
I tried to focus on the biggest new things we are offering now, 
topics we didn't have before and now we need to start from scratch.


The Geronimo v2.1 documentation space is already available here 
http://cwiki.apache.org/GMOxDOC21/documentation.html


The initial TOC includes:

* Configuration changes
* Deployment
** Deployment plan creator
* Geronimo Administration Console enhancements
* GShell
* Monitoring
* Pluggable console
* Plugin infrastructure enhancements
* RELEASE-NOTES-2.1.TXT
* Sample applications
* Security
* Tooling
* What's new?

Each of these pages already contain a few lines with some initial 
thoughts. Need your input for adding topics to this list as well as 
developing them.
There might be things we already had in 2.0x but we didn't cover it 
in the doc, pls need your comments on that as well.


I think I'm finish covering *Deployment plan creator*, will do a 
refresh later on as new code gets in.


I also created this "place holder" 
http://cwiki.apache.org/GMOxPMGT/geronimo-v21-list-of-functions-status.html 
under *Apache Geronimo Project Management* on the wiki so we can 
keep track there the features we have ready for prime time and those 
that are not so ready ;-)  I could definitively use that info to 
build up a new set of docs, would also help users to see where we 
are at.

Hernan,
Thanks for this. Time to start pulling these docs together to prepare 
for release. It can't all be generated by Hernan. We'll need to chip 
in...

--kevan

Re: Geronimo v2.1 documentation

[David Jencks]

On Feb 5, 2008, at 4:31 PM, David Jencks wrote:

Would it be possible to link to the in-progress 2.1 documentation  
from what I think is the main docs page http://geronimo.apache.org/ 
documentation.html?


I'm also wondering whether there is some way to make the existence of

http://cwiki.apache.org/GMOxDOC21/documentation.html

more obvious from

http://cwiki.apache.org/GMOxDOC21/

which seems to be what I always find when I look for the 2.1 docs.


I also realize I don't know what the intended relationship between  
these pages is and which one I'm supposed to work from and how (or  
if) to affect the *documentation.html page.   A few days ago I wrote  
up info on a new jndi feature which shows up fine on the / page but  
not the documentation.html.




thanks
david jencks



Are there plans to copy the parts of the 1.x and 2.0.x docs that  
are still relevant to the 2.1 docs?  I think this did not happen  
completely for the 1.1 >> 2.0 release.


thanks
david jencks


On Jan 25, 2008, at 8: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.


Cheers!
Hernan

Kevan Miller wrote:

On Jan 10, 2008, at 5:14 PM, Hernan Cunico wrote:

Hi All,
some time ago I started to put together some topics for Geronimo  
v2.1 documentation.
I tried to focus on the biggest new things we are offering now,  
topics we didn't have before and now we need to start from scratch.


The Geronimo v2.1 documentation space is already available here  
http://cwiki.apache.org/GMOxDOC21/documentation.html


The initial TOC includes:

* Configuration changes
* Deployment
** Deployment plan creator
* Geronimo Administration Console enhancements
* GShell
* Monitoring
* Pluggable console
* Plugin infrastructure enhancements
* RELEASE-NOTES-2.1.TXT
* Sample applications
* Security
* Tooling
* What's new?

Each of these pages already contain a few lines with some  
initial thoughts. Need your input for adding topics to this list  
as well as developing them.
There might be things we already had in 2.0x but we didn't cover  
it in the doc, pls need your comments on that as well.


I think I'm finish covering *Deployment plan creator*, will do a  
refresh later on as new code gets in.


I also created this "place holder" http://cwiki.apache.org/ 
GMOxPMGT/geronimo-v21-list-of-functions-status.html under  
*Apache Geronimo Project Management* on the wiki so we can keep  
track there the features we have ready for prime time and those  
that are not so ready ;-)  I could definitively use that info to  
build up a new set of docs, would also help users to see where  
we are at.

Hernan,
Thanks for this. Time to start pulling these docs together to  
prepare for release. It can't all be generated by Hernan. We'll  
need to chip in...

--kevan

Re: Geronimo v2.1 documentation

[David Jencks]

Would it be possible to link to the in-progress 2.1 documentation  
from what I think is the main docs page http://geronimo.apache.org/ 
documentation.html?


I'm also wondering whether there is some way to make the existence of

http://cwiki.apache.org/GMOxDOC21/documentation.html

more obvious from

http://cwiki.apache.org/GMOxDOC21/

which seems to be what I always find when I look for the 2.1 docs.

Are there plans to copy the parts of the 1.x and 2.0.x docs that are  
still relevant to the 2.1 docs?  I think this did not happen  
completely for the 1.1 >> 2.0 release.


thanks
david jencks


On Jan 25, 2008, at 8: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.


Cheers!
Hernan

Kevan Miller wrote:

On Jan 10, 2008, at 5:14 PM, Hernan Cunico wrote:

Hi All,
some time ago I started to put together some topics for Geronimo  
v2.1 documentation.
I tried to focus on the biggest new things we are offering now,  
topics we didn't have before and now we need to start from scratch.


The Geronimo v2.1 documentation space is already available here  
http://cwiki.apache.org/GMOxDOC21/documentation.html


The initial TOC includes:

* Configuration changes
* Deployment
** Deployment plan creator
* Geronimo Administration Console enhancements
* GShell
* Monitoring
* Pluggable console
* Plugin infrastructure enhancements
* RELEASE-NOTES-2.1.TXT
* Sample applications
* Security
* Tooling
* What's new?

Each of these pages already contain a few lines with some initial  
thoughts. Need your input for adding topics to this list as well  
as developing them.
There might be things we already had in 2.0x but we didn't cover  
it in the doc, pls need your comments on that as well.


I think I'm finish covering *Deployment plan creator*, will do a  
refresh later on as new code gets in.


I also created this "place holder" http://cwiki.apache.org/ 
GMOxPMGT/geronimo-v21-list-of-functions-status.html under *Apache  
Geronimo Project Management* on the wiki so we can keep track  
there the features we have ready for prime time and those that  
are not so ready ;-)  I could definitively use that info to build  
up a new set of docs, would also help users to see where we are at.

Hernan,
Thanks for this. Time to start pulling these docs together to  
prepare for release. It can't all be generated by Hernan. We'll  
need to chip in...

--kevan

Re: Geronimo v2.1 documentation

[Hernan Cunico]

Hi Jay,
as I said on another reply, don't worry about the wiki format, doc structure or 
refined content, I'll take that bullet.

We need to focus on what to cover and how. When we have the content, it is easier to move it around within the wiki, edit it and to give it a consistent look with the rest of the docs. 


If you want to look into the formatting we've been using in the past, I created 
this page long time ago to help me (and everybody adding content) be consistent 
with the existing doc. 
http://cwiki.apache.org/geronimo/tips-for-writing-and-formatting-documentation.html

I'm about to shoot a separate thread for discussing the content, pls chime in 
with your ideas, I'll put there mine as well ;-)

Cheers!
Hernan

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

Re: Geronimo v2.1 documentation

[Hernan Cunico]

Hey BJ,
I think the newer the better :D
We need to capture all the questions you are having about Geronimo as a new 
user and merge them with the other questions we see from the user's list and 
feed it back into the table of contents.
Being a new user gives you a perspective that sometimes we may overlook.

I'll initiate a separate thread to discuss the topics to cover. Everybody pls 
chime into that thread for content discussion.

Cheers!
Hernan

B.J. Reed wrote:

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.

Re: Geronimo v2.1 documentation

[Hernan Cunico]

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

Re: Geronimo v2.1 documentation

[B.J. Reed]

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.

Re: Geronimo v2.1 documentation

[Jay D. McHugh]

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

Re: Geronimo v2.1 documentation

[Kevan Miller]

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

Re: Geronimo v2.1 documentation

[Hernan Cunico]

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.

Cheers!
Hernan

Kevan Miller wrote:


On Jan 10, 2008, at 5:14 PM, Hernan Cunico wrote:


Hi All,
some time ago I started to put together some topics for Geronimo v2.1 
documentation.
I tried to focus on the biggest new things we are offering now, topics 
we didn't have before and now we need to start from scratch.


The Geronimo v2.1 documentation space is already available here 
http://cwiki.apache.org/GMOxDOC21/documentation.html


The initial TOC includes:

* Configuration changes
* Deployment
** Deployment plan creator
* Geronimo Administration Console enhancements
* GShell
* Monitoring
* Pluggable console
* Plugin infrastructure enhancements
* RELEASE-NOTES-2.1.TXT
* Sample applications
* Security
* Tooling
* What's new?

Each of these pages already contain a few lines with some initial 
thoughts. Need your input for adding topics to this list as well as 
developing them.
There might be things we already had in 2.0x but we didn't cover it in 
the doc, pls need your comments on that as well.


I think I'm finish covering *Deployment plan creator*, will do a 
refresh later on as new code gets in.


I also created this "place holder" 
http://cwiki.apache.org/GMOxPMGT/geronimo-v21-list-of-functions-status.html 
under *Apache Geronimo Project Management* on the wiki so we can keep 
track there the features we have ready for prime time and those that 
are not so ready ;-)  I could definitively use that info to build up a 
new set of docs, would also help users to see where we are at.


Hernan,
Thanks for this. 

Time to start pulling these docs together to prepare for release. It 
can't all be generated by Hernan. We'll need to chip in...


--kevan

Re: Geronimo v2.1 documentation

[Kevan Miller]

On Jan 10, 2008, at 5:14 PM, Hernan Cunico wrote:


Hi All,
some time ago I started to put together some topics for Geronimo  
v2.1 documentation.
I tried to focus on the biggest new things we are offering now,  
topics we didn't have before and now we need to start from scratch.


The Geronimo v2.1 documentation space is already available here 
http://cwiki.apache.org/GMOxDOC21/documentation.html

The initial TOC includes:

* Configuration changes
* Deployment
** Deployment plan creator
* Geronimo Administration Console enhancements
* GShell
* Monitoring
* Pluggable console
* Plugin infrastructure enhancements
* RELEASE-NOTES-2.1.TXT
* Sample applications
* Security
* Tooling
* What's new?

Each of these pages already contain a few lines with some initial  
thoughts. Need your input for adding topics to this list as well as  
developing them.
There might be things we already had in 2.0x but we didn't cover it  
in the doc, pls need your comments on that as well.


I think I'm finish covering *Deployment plan creator*, will do a  
refresh later on as new code gets in.


I also created this "place holder" http://cwiki.apache.org/GMOxPMGT/geronimo-v21-list-of-functions-status.html 
 under *Apache Geronimo Project Management* on the wiki so we can  
keep track there the features we have ready for prime time and those  
that are not so ready ;-)  I could definitively use that info to  
build up a new set of docs, would also help users to see where we  
are at.


Hernan,
Thanks for this.

Time to start pulling these docs together to prepare for release. It  
can't all be generated by Hernan. We'll need to chip in...


--kevan