geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jack <>
Subject Re: Documentation of new 2.2 features in current wiki?
Date Fri, 08 Aug 2008 08:45:08 GMT
Thanks Joe for all the work here!

After going through the new structure proposed by Rebekah, I would say it is
a "derived" version from 2.1, instead of a whole new structure. So I don't
think somebody familar with the current 2.1 structure would need much time
to get familiar with the new structure. And for new users, the new structure
seems earier to start with. It is more natural and is better organized from
user's point of view, instead of technology-oriented. Users turn to the
documentation when they met some problems and cannot figure it out by
exploring the software alone(so ideal software should be self-evident with
their UI and do not need any doc :-)), so many product documentation
nowadays are usally scenario or task oriented. I guess Rebekah can do a
better job in explaining this to us since she has been working on product
documentation for several years.

We do have some resource available to do the migration from 2.1 to 2.2 doc
manually. So if we could agree that we can have a better doc structure, we
can put the new structure on the new wiki space and have more discussion on
the structure itself. We definitely need your opinions to make it better...

Currently Rebekah has made 2 proposals, 1 follows 2.1 which divides the doc
into user's guide and developer's guide, the other integrates them together.
Personally I prefer the latter because it simplifies user's view. I would
say most, if not all, geronimo "users" are also "developers". So it will be
easier for user to locate information based on their tasks instead of asking
them to decide whether he/she is a user or a developer beforehands (which
typically ends up browsing both guides).

Open for your comments.

View raw message