geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hernan Cunico <hcun...@gmail.com>
Subject Re: [DISCUSSION] Geronimo v2.1 documentation - Content
Date Fri, 22 Feb 2008 19:51:33 GMT
Jason Warner wrote:
> 
> On Fri, Feb 22, 2008 at 12:05 PM, Donald Woods <dwoods@apache.org 
> <mailto:dwoods@apache.org>> wrote:
> 
>     I think J2G should stay listed as a "Tool".  Anything that requires a
>     developer tool like Eclipse in-order to use it, should be called a tool.
> 
> 
> I half agree with what you're saying.  Part of me does want J2G to be in 
> the tools section, because it does belong there.  I also think it 
> belongs in our migration section, though, and I don't think it's a good 
> idea to put it in both.  In my mind, people that are looking for a way 
> to migrate to geronimo are much more likely to look in a section labeled 
> migration rather than the tool section.  I'm afraid users will miss it 
> if it's left in the tools section.  I suppose I could put it back in the 
> tools section and then we could add a link to it from the migration 
> section. I kind of wish I had thought of that earlier as it's a pretty 
> simple solution.  I'm going to wait for a response until doing that, 
> though.
>  
>

Yes, it is a very simple solution. I think the description of the J2G belongs to the tooling
section and how to use it, working examples and migration samples belong to a Migration section.
In the Tooling we may want to focus on describing what are the tools available, what do they
do, why, etc. but not necessarily cover in detail the "how to"

In the Migration section, when covering migration from different platforms/vendors, you reference
to the tooling section for details on this tool and then quickly turn into how to use the
J2G migration tool providing examples, tutorials, sample apps, whatever is needed to get the
message through.

Cheers!
Hernan

> 
>     I always view a "Migration" section in a product's docs as how to
>     migrate from prior releases, whereas migrating from other vendors
>     products is complicated enough to deserve its own set of docs, samples
>     and tutorials.
> 
> I'm not sure what you're saying here.  I think the migration section is 
> fairly explicit in that it is for migrating an app to Apache Geronimo.  
> Were you looking to separate it into a whole new document that isn't 
> included in the documentation? 
>  
> 
> 
> 
>     -Donald
> 
> 
>     Jason Warner wrote:
>      > I was looking at transferring the J2G documentation over from 2.0
>     to 2.1
>      > and I noticed that j2g is listed under tools rather than a migration
>      > heading.  Are we not going to have a Migration heading?  I'd
>     prefer to
>      > put the tool under something more descriptive so that it really jumps
>      > out to a user.  Also, there were some migration sample documents that
>      > are now left homeless.  I guess I'm wondering if we should bring back
>      > the migration heading.  Thoughts anyone?
>      >
>      > On Thu, Feb 21, 2008 at 1:49 PM, Hernan Cunico <hcunico@gmail.com
>     <mailto:hcunico@gmail.com>
>      > <mailto:hcunico@gmail.com <mailto:hcunico@gmail.com>>> wrote:
>      >
>      >     Lin Sun wrote:
>      >      > Hi Hernan, I looked at the index you put out there and I
>     think it is
>      >      > very good!  I cannot wait for these contents to be filled to
>      >      > understand a bit more about these exciting 2.1 new features!!
>      >      >
>      >      > I think it'll be useful to add a FAQ or troubleshooting
>     section.   I
>      >      > hope this can be the first place for a user to look at
>     whenever they
>      >      > run into some probs/exceptions.    The content can grow
>     based on the
>      >      > questions we get on the user list.
>      >
>      >     At some point we had a Troubleshooting section, maybe I forgot to
>      >     bring the title over 2.1 doc. I just added the entry on the
>     User's
>      >     guide side.
>      >     Ideally the Troubleshooting section should be a subset, an
>     excerpt
>      >     of some of the other areas already covered. I personally think of
>      >     Troubleshooting section more like a convenience section.
>      >
>      >     Agree with you that ultimately we want to address every single
>      >     question from the user list. Hernan's view of the world!? if
>     a user
>      >     have an issue doing a task on Geronimo that means that A) G
>     is not
>      >     intuitive enough, B) we don't provide enough documentation on
>     how to
>      >     perform such task, C) we do have that info but it is a secret
>     well
>      >     kept and only a few know about it ;-) , D) all of the above.
>      >
>      >     With that said, tackling an issue on the Troubleshooting
>     section is
>      >     a great start but we shouldn't stop there ;-)
>      >
>      >      >
>      >      > Also, I think the sample application and tutorial sections
>     are a bit
>      >      > confusion.  First I look at the sample application and saw
>     we only
>      >      > have 2 down there but then I realized most of the samples
>     are in the
>      >      > tutorial section.
>      >
>      >     The User's guide on the left is somewhat a carry over of
>     topics from
>      >     2.0. For 2.1 I brought back the idea of the Developer's guide and
>      >     put the Tutorials section there in contrast with Samples section
>      >     from the User's guide. If you look at the Tutorials you'll
>     see there
>      >     is a different approach, it is more aligned with developing
>      >     applications with GEP for instance, hence the location on the
>      >     Developer's guide.
>      >
>      >     Sample applications could end up being renamed to just
>     Samples as it
>      >     included some sample configurations as well.
>      >
>      >     Either way, The doc is still on its early stages and this may
>     change
>      >     as we continue to develop the content.
>      >
>      >     As usual, comments, new ideas and most definitively doc
>      >     contributions are always welcome
>      >
>      >
>      >     Cheers!
>      >     Hernan
>      >
>      >      >
>      >      > Lin
>      >      >
>      >      > On Mon, Feb 18, 2008 at 10:23 AM, Hernan Cunico
>      >     <hcunico@gmail.com <mailto:hcunico@gmail.com>
>     <mailto:hcunico@gmail.com <mailto:hcunico@gmail.com>>> wrote:
>      >      >> Hey Kevan, Thanks for updating the doc.
>      >      >>
>      >      >>  I thought it would be useful for the users to know what
>      >     versions are we using for the components/projects that make
>     Geronimo
>      >     v2.1
>      >      >>  For example, what version of Tomcat, Jetty, Derby, Axis...
>      >      >>
>      >      >>  It would even help us to keep track of the components and
>      >     versions, all in one place.
>      >      >>
>      >      >>  Maybe this info could later on live on the Geronimo
>      >     architecture section. Once we have the info it's easier to move.
>      >      >>
>      >      >>  Cheers!
>      >      >>  Hernan
>      >      >>
>      >      >>
>      >      >>
>      >      >>  Kevan Miller wrote:
>      >      >>  >
>      >      >>  > On Jan 28, 2008, at 11:48 AM, Hernan Cunico wrote:
>      >      >>  >
>      >      >>  >> Hi All,
>      >      >>  >> these are some of the topics I think we should cover
>     for the 2.1
>      >      >>  >> documentation. It is not a full list so we need your
>     help to
>      >     make it
>      >      >>  >> as complete as possible. Pls chime in with the topics
you
>      >     would like
>      >      >>  >> to see addressed in the documentation.
>      >      >>  >>
>      >      >>  >> * What's new in 2.1?
>      >      >>  >> ** New features
>      >      >>  >> ** Component versions
>      >      >>  >> ** Configuration changes
>      >      >>  >> ** Backwards compatibility
>      >      >>  >
>      >      >>  > Hernan,
>      >      >>  > I've fleshed out the "New Features" a bit in cwiki.
>     Can you
>      >     explain what
>      >      >>  > you meant by "Component versions"?
>      >      >>  >
>      >      >>  > --kevan
>      >      >>  >
>      >      >>
>      >      >
>      >
>      >
>      >
>      >
>      > --
>      > ~Jason Warner
> 
> 
> 
> 
> -- 
> ~Jason Warner

Mime
View raw message