You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@geronimo.apache.org by "Geir Magnusson Jr." <ge...@apache.org> on 2005/10/28 21:41:23 UTC
New Solaris Zones
The solaris zones for Geronimo are being created, one for general
project use and one for tck use.
How shall we administer them?
geir
--
Geir Magnusson Jr +1-203-665-6437
geirm@apache.org
Re: New Solaris Zones
Posted by Bruce Snyder <br...@gmail.com>.
On 10/28/05, Dain Sundstrom <da...@iq80.com> wrote:
> I think we should give all committers accounts. As for sudo access,
> I think we should give it to a couple of committers that have a good
> unix background and are willing to help. I'm willing to help, but my
> unix skills are weak. I'm personally hoping that David Blevins
> (hint) and Jeff Genender volunteer (hint) as both of them have mad
> unix admin skills :)
I'm a Unix nut myself and I'd love to be involved in this. If
possible, count me in.
Bruce
--
perl -e 'print unpack("u30","D0G)U8V4\@4VYY9&5R\"F)R=6-E+G-N>61E<D\!G;6%I;\"YC;VT*"
);'
The Castor Project
http://www.castor.org/
Apache Geronimo
http://geronimo.apache.org/
Re: New Solaris Zones
Posted by "Geir Magnusson Jr." <ge...@apache.org>.
That's one...
On Oct 28, 2005, at 4:43 PM, David Blevins wrote:
> Happy to volunteer to admin our stuff.
>
> -David
>
> On Oct 28, 2005, at 1:34 PM, Dain Sundstrom wrote:
>
>
>> I think we should give all committers accounts. As for sudo
>> access, I think we should give it to a couple of committers that
>> have a good unix background and are willing to help. I'm willing
>> to help, but my unix skills are weak. I'm personally hoping that
>> David Blevins (hint) and Jeff Genender volunteer (hint) as both of
>> them have mad unix admin skills :)
>>
>> I think we should apply the same rules to the geronimo-tck zone
>> except that only NDA signers would get access.
>>
>> -dain
>>
>> On Oct 28, 2005, at 12:41 PM, Geir Magnusson Jr. wrote:
>>
>>
>>
>>> The solaris zones for Geronimo are being created, one for general
>>> project use and one for tck use.
>>>
>>> How shall we administer them?
>>>
>>> geir
>>>
>>> --
>>> Geir Magnusson Jr +1-203-665-6437
>>> geirm@apache.org
>>>
>>>
>>>
>>>
>>
>>
>>
>
>
--
Geir Magnusson Jr +1-203-665-6437
geirm@apache.org
Re: New Solaris Zones
Posted by David Blevins <da...@visi.com>.
Happy to volunteer to admin our stuff.
-David
On Oct 28, 2005, at 1:34 PM, Dain Sundstrom wrote:
> I think we should give all committers accounts. As for sudo
> access, I think we should give it to a couple of committers that
> have a good unix background and are willing to help. I'm willing
> to help, but my unix skills are weak. I'm personally hoping that
> David Blevins (hint) and Jeff Genender volunteer (hint) as both of
> them have mad unix admin skills :)
>
> I think we should apply the same rules to the geronimo-tck zone
> except that only NDA signers would get access.
>
> -dain
>
> On Oct 28, 2005, at 12:41 PM, Geir Magnusson Jr. wrote:
>
>
>> The solaris zones for Geronimo are being created, one for general
>> project use and one for tck use.
>>
>> How shall we administer them?
>>
>> geir
>>
>> --
>> Geir Magnusson Jr +1-203-665-6437
>> geirm@apache.org
>>
>>
>>
>
>
Re: Wiki reorganization proposal
Posted by "Geir Magnusson Jr." <ge...@apache.org>.
me too. what camera?
On Oct 28, 2005, at 6:47 PM, Dain Sundstrom wrote:
> On Oct 28, 2005, at 3:41 PM, Geir Magnusson Jr. wrote:
>
>
>> Don't let us stand in your way... looks good to me...
>>
>> My only comment after a quick read through is to put the stuff to
>> help people get started right at the top. Sorta like when you get
>> a camera or something it has a 1 page "Instructions for the
>> Impatient" or something.
>>
>
> Big +1
>
> I just got a new camera the other day, and that was the only
> section I read.
>
> -dain
>
--
Geir Magnusson Jr +1-203-665-6437
geirm@apache.org
Re: Wiki reorganization proposal
Posted by Dain Sundstrom <da...@iq80.com>.
On Oct 28, 2005, at 3:41 PM, Geir Magnusson Jr. wrote:
> Don't let us stand in your way... looks good to me...
>
> My only comment after a quick read through is to put the stuff to
> help people get started right at the top. Sorta like when you get
> a camera or something it has a 1 page "Instructions for the
> Impatient" or something.
Big +1
I just got a new camera the other day, and that was the only section
I read.
-dain
Re: Wiki reorganization proposal
Posted by "Geir Magnusson Jr." <ge...@apache.org>.
Don't let us stand in your way... looks good to me...
My only comment after a quick read through is to put the stuff to
help people get started right at the top. Sorta like when you get a
camera or something it has a 1 page "Instructions for the Impatient"
or something. I'd also rather see project overview be the website.
I first thought about two groupings - user/admin and developer, but
it's not really clear how things would fall - ex, does app migration
go to user or dev?
Anyway, soemthing like
Installation
Administration
Hints and Tips
Architecture
Dev
...
I think what you have for each bucket is great, btw...
Nice.
geir
On Oct 28, 2005, at 5:52 PM, Hernan Cunico wrote:
> Hi All,
> Independently of whether we will ever move wiki to confluence or
> not (there is a lot of discussion on this) still the Apache wiki
> needs some serious reorganization today.
>
> I think it should be restructured into something easier to browse,
> making a stronger focus on the Geronimo documentation. We could
> have sections at the bottom (sort of Appendixes) for all non-
> documentation related topics (people, contests, etc).
>
> This is the content as it is today:
>
> About
> Logo Contest
> Downloads
> Documentation
> Mailing Lists
> Issue Tracking
> Related Sites
> Project Status & Management
> Developer Information
> ObjectWeb Collaboration
> People
> Wiki Sand Box
>
>
> Most of this information is either redundant on the
> geronimo.apache.org front page or not relevant (like "Related sites").
>
> My suggestion is to provide a logical flow, from "the generic" to
> "the specific". Start with a "Project overview", then go with the
> "Geronimo architecture" and continue with a breakdown of that
> architecture, ...
>
> The structure I propose may look like a TOC for a book but,
> dreaming about a perfect world, it would be great if Geronimo can
> have a sound starting point for our documentation. I see other wiki-
> like sites and are a lot more organized.
>
> Here is my proposed content for the wiki:
>
> - Apache Geronimo project overview
> - About ASF
> - Licensing
>
> - Architecture
> - GBeans
> - Geronimo kernel
> - Naming
> - Tomcat
> - Jetty
> - Derby
> - Axis
> - TranQL
> - OpenEJB
> - MX4J
> - ActiveMQ
> - ApacheDS
> - ...
>
> - Installation
> - Platforms supported
> - Hardware and software prerequisites
> - Getting the source code
> - Build from the source
> - Installation
>
> - Administration
> - Tools
> start and stop services/servers, deployer.jar, etc
> - Geronimo Web Console
> - Configure resources
> - JavaMail
> - Database
> - ...
> - Logging
> - Backup and recovery
> - Maintenance
>
> - Development
> - Eclipse tools
> - Simple servlet and JSP applications
> - Web applications
> - EJB applications
> - Security applications
> - Web services applications
> - Client applications
> - ...
>
> - Deployment
> - Deployer tool
> - Deployment plans
> - Deploying applications
> - Deploying configurations/resources
>
> - Security
> - Implementation overview
> - Authentication
> - Authorization
> - Security modules
> - Security realms
> - Enabling SSL
> - Programatic security
> - Enabling security for applications
> - LDAP
>
> - Applications migration
>
> - Performance and high availability
> - Scalability
> - Clustering
>
> - Hints and Tips
>
> - Troubleshooting
>
> - Sample applications
>
> - Other interesting resources
> - Wiki SandBox
> - People
>
>
> I know I'm missing a lot but still wanted to give this first step.
>
> I'm sure with a better structure we can get more people easily
> invovled on both, producing and consuming, documentation.
>
> Thank you all.
>
>
> Cheers!
> Hernan
>
--
Geir Magnusson Jr +1-203-665-6437
geirm@apache.org
Re: Wiki reorganization proposal
Posted by Hernan Cunico <hc...@gmail.com>.
Hi John,
Since this note is growing a lot, I wanted to summarize here some the
key things we need to address:
- Everybody, need more comments/opinions here!
- Review documentation strategy (what, where, how...)
- Define versioning policy for documentation.
- Create separated sections for each version.
- Move existing documentation to the corresponding new sections.
- Define update policy when code fixes impact the current documentation.
- Finish TOC for the new sections.
- Define a "Geronimo Central" for documentation (wiki, confluence, ...).
Should we try to consolidate all the documentation in one place? which
one would be the best?
Comments inline.
Cheers!
Hernan
John Sisson wrote:
> Hi Hernan,
>
> I hope you don't feel that I don't want the wiki restructured, I just
> think we should discuss what the wiki should be used for and how we
> should deliver documentation for release x of Geronimo, accomodating
> future requirements.
don't worry, we are on the same page, just using different words :)
>
> IMHO, Geronimo for a large proportion of users is only as good as its
> documentation, which needs a rethink. Look forward to an interesting
> discussion.
Totally agree, need more people jumping to this discussion.
>
> Others please chime in.
>
> Comments inline below..
>
> Regards,
>
> John
>
> Hernan Cunico wrote:
>
>> Hi John,
>>
>> It will be very hard to keep updated all the documentation as new
>> branches/releases come available. See comments inline
>>
>> Cheers!
>> Hernan
>>
>>
>> John Sisson wrote:
>>
>>> Hi Hernan,
>>>
>>> The suggested layout sounds fine to me. This is long overdue and is
>>> an opportunity to remove/move/fix documentation that no longer
>>> matches what has been implemented.
>>>
>>> My main concern with the use of the Wiki for documentation is that
>>> the Wiki content isn't versioned to match Geronimo releases.
>>
>>
>>
>> wiki should not be versioned the same way Geronimo is. I would say,
>> wiki should keep the pace of mayor milestones (M1, M5, V1...)
>>
>>>
>>> For example, if you go to the page about building Geronimo with
>>> eclipse and try using that with M4 you will have problems as the
>>> documentation relies upon changes since M4.
>>
>>
>>
>> Maybe a commmon header for all docs stating versions used would
>> address this issue.
>
>
> Are you saying we have a different version of each document for each
> version?
>
> We should be able to have an easily accessible archive of doco for a
> particular version of Geronimo. A user who adopts 1.0 should be able to
> access the documentation for it (without it being polluted with updates
> from later releases that are not relevant to 1.0) for at least a few years.
I think we are saying the same thing with different words. What I was
suggesting was to just focus on major G versions (M4, M5, V1, ...) for
versioning the documentation. What I think we should avoid is to have as
many flavors of the same doc as intermediate G versions become
available. Version.Release.Modification (V.R.M - 0.5.0). Otherwise it
would be impossible to maintain.
Maybe I'm confusing the terms (version/release). Some clarification will
be more than welcome.
>
>>
>> ... These are the versions used for this doc, other versions have not
>> been tested and may not work...
>
>
> IMHO, wording like that in documentation normally wouldn't cut it in
> commercial software. I think we are lacking a thought out strategy on
> documentation. Sure there will be a few books that will be released on
> Geronimo, but I don't think we should be relying upon them for
> documentation. Will they be able to put updated versions of these books
> with at the same time we put out a new geronimo release?
OK, that was a bad line. Still spinning around the same "version" issue.
I never mentioned anything about other books, if books become available
that would be great (as a complement of the G documentation on wiki,
confluence, ...)
What I wanted to say on that line was that we can only provide
documentation for some versions (major ones, M4, M5, V1, ...) and not
for all those in between.
>
> I view the wiki as a place that users can contribute notes or tips on
> Geronimo usage that should eventually be fed into formal (printable as a
> manual) documentation that is associated with each release.
wiki is great for everybody to add comments and fix the existing
documentation. I put some articles in confluence which allows you to
export in PDF, HTML or XML not only individual articles but entire
sections (Thanks Dain for the tip)
You just need to be logged in confluence to use this link
http://opensource2.atlassian.com/confluence/oss/spaces/exportspace.action?key=GERONIMO
>
>>
>>>
>>> There have been other pages that have comments about what version
>>> they are applicable to (e.g. for M4 do this, but for M5 do that), but
>>> a user reading documentation for M5 doesn't want to have to skip all
>>> the bits about M4 for example.
>>
>>
>>
>> I agree, I don't think it will be a good solution having a doc
>> covering topic "A" and having having multiple entries to explain the
>> same procedure for M4, M5, V1, ...
>
>
> We need a solution for this issue. Can others chime in here with
> suggestions?
Once we have identified how to deal with the versions/releases I think
it would be easier to address this issue.
>
>>
>>>
>>> Is it possible to easily branch/copy the Wiki documentation when we
>>> do a release? For example, for the 1.0 release a branch of the Wiki
>>> is done so that the 1.0 documentation is easily accessible and can be
>>> updated if needed after 1.0 is released.
>>
>>
>>
>> Creating a new V1 branch for the wiki will imply not just to "copy"
>> some of the already available documentation but verifying each doc for
>> accuracy and compatibility with V1. Sort of "V1 Certified" instructions.
>>
>> I would say this process should not be automatic, it would require a
>> thorough reviewing of all the existing documentation.
>>
>
> I agree that it would require reviewing. I am hoping that if we come up
> with a structured manual, when code changes are made, if there is an
> impact to the documentation then the developer will make the appropriate
> documentation changes. Other projects do this, why shouldn't we?
> Currently I think it is hard to find parts of the wiki that need
> updating when code changes are made, since it isn't structured in a way
> that is easy to find the related doco.
Having the developers updating the documentation as they fix the code
would be great. We should define a process where the
developer/contributor provides the code fix to the committer along with
the piece of documentation to update. This way the documentation would
be updated once the fix is "implemented". (just an idea)
>
>>>
>>> An issue I can see with branching/copying the Wiki content for each
>>> release is that some users may update the doco in the branch, but not
>>> the main doco that will be used for the next release.
>>
>> Yup, this wil be an additional issue.
>>
>> Maybe we should create an entry (I wouldn't call them branches as they
>> would be more like the "release" type, main docs.) for M4, one for M5
>> and one for the upcoming versions. We have some M4 and M5 docs today,
>> I would suggest to separate the docs by version/milestone and focus on
>> finishing M5, have this milestone as complete as possible creating the
>> foundation for V1 doc.
>>
>
> This sounds like it is heading in the right direction, but doesn't solve
> the printable manual option. Think a year or two down the track.. I
> don't think the documentation will be small, so printing documentation
> page by page does not sound appropriate. I think we need to be able to
> print a PDF with the full bookmarks/hyperlinking etc (like the Derby doco).
I think we may have a solution for this already as commented earlier in
this note.
>
>>>
>>> I like Wikis, except for the problem described above. I can only see
>>> this problem getting worse as more releases are shipped.
>>>
>>> An alternative is to develop the main documentation under svn control
>>> (the Derby project does this), but that would mean updates would have
>>> to be submitted as patches. Derby's doco can be easily generated as
>>> a PDF with bookmarks etc, which is great for offline or printing.
>>
>>
>>
>> Not sure if submitting updated as patches would be an issue. What is
>> not clear to me is svn. Isn't a version control alrady in place for
>> the documentation?
>
>
> AFAIK, it is date versioned, but the wiki doesn't natively support
> branches of documentation and tagging of releases. How easy is it to
> make a copy of all M5 doco for the basis of M6 doco in the wiki? Any
> wiki admin gurus here?
>
>>
>> It would be great to have a better "Show diff" functionality so you
>> not only know there is a new version, but also know what's changed.
>
>
> AFAIK, you can do diffs in the wiki now (may not be easy for those
> unfamiliar with wikis to use).
I was thinking in a more WYSIWYG like and not wiki "code". Geronimo
documentation consumers should focus on Geronimo and not on
understanding wiki formating.
Better documentation we provide, more users will move to Geronimo.
>
>>
>>>
>>> Maybe IBM be interested in taking a similar approach with the
>>> documentation as Derby (contributing docs and resources for docs and
>>> using it as a basis of their commercial product docs), as far as I
>>> can tell, the Cloudscape doco is based on the open source Derby doco?
>>
>>
>>
>> Not sure what you mean!?
>>
>
> The Derby printed documentation is not from a wiki, AFAIK, they use DITA
> (Darwin Informatation Typing Architecture) sourced XML documentation
> that can be converted to both PDF and HTML book/files formats using
> Apache FOP.
>
> They have 6 manuals that have been produced using this.
>
> http://db.apache.org/derby/manuals/dita.html
>
> AFAIK, IBM's Cloudscape's documentation is based upon the documentation
> contributed to Derby. Derby is probably not the best example since when
> the documentation was initially contributed by IBM it was pretty much
> complete, since they contributed what was the Cloudscape documentation
> (please correct me if I am wrong).
>
> I was wondering whether IBM or any other ISV that is considering
> producing their own documentation for products derived from Geronimo
> consider whether there would be benefits in contributing Geronimo
> documentation to the Apache Geronimo project and use that as a base of
> their customised documentation. Maybe we should speak with the Derby
> project and ask for their experiences with their current documentation
> processes.
>
>
>>>
>>> No harm in asking :-) ?
>>>
>>> Regards,
>>>
>>> John
>>>
>>> Hernan Cunico wrote:
>>>
>>>> Hi All,
>>>> Independently of whether we will ever move wiki to confluence or not
>>>> (there is a lot of discussion on this) still the Apache wiki needs
>>>> some serious reorganization today.
>>>>
>>>> I think it should be restructured into something easier to browse,
>>>> making a stronger focus on the Geronimo documentation. We could have
>>>> sections at the bottom (sort of Appendixes) for all
>>>> non-documentation related topics (people, contests, etc).
>>>>
>>>> This is the content as it is today:
>>>>
>>>> About
>>>> Logo Contest
>>>> Downloads
>>>> Documentation
>>>> Mailing Lists
>>>> Issue Tracking
>>>> Related Sites
>>>> Project Status & Management
>>>> Developer Information
>>>> ObjectWeb Collaboration
>>>> People
>>>> Wiki Sand Box
>>>>
>>>>
>>>> Most of this information is either redundant on the
>>>> geronimo.apache.org front page or not relevant (like "Related sites").
>>>>
>>>> My suggestion is to provide a logical flow, from "the generic" to
>>>> "the specific". Start with a "Project overview", then go with the
>>>> "Geronimo architecture" and continue with a breakdown of that
>>>> architecture, ...
>>>>
>>>> The structure I propose may look like a TOC for a book but, dreaming
>>>> about a perfect world, it would be great if Geronimo can have a
>>>> sound starting point for our documentation. I see other wiki-like
>>>> sites and are a lot more organized.
>>>>
>>>> Here is my proposed content for the wiki:
>>>>
- Geronimo for the impatiens (aka Compressed Getting Started)
>>>> - Apache Geronimo project overview
>>>> - About ASF
>>>> - Licensing
>>>>
>>>> - Architecture
>>>> - GBeans
>>>> - Geronimo kernel
>>>> - Naming
>>>> - Tomcat
>>>> - Jetty
>>>> - Derby
>>>> - Axis
>>>> - TranQL
>>>> - OpenEJB
>>>> - MX4J
>>>> - ActiveMQ
>>>> - ApacheDS
>>>> - ...
>>>>
>>>> - Installation
>>>> - Platforms supported
>>>> - Hardware and software prerequisites
>>>> - Getting the source code
>>>> - Build from the source
>>>> - Installation
>>>>
>>>> - Administration
>>>> - Tools
>>>> start and stop services/servers, deployer.jar, etc
>>>> - Geronimo Web Console
>>>> - Configure resources
>>>> - JavaMail
>>>> - Database
>>>> - ...
>>>> - Logging
>>>> - Backup and recovery
>>>> - Maintenance
>>>>
>>>> - Development
>>>> - Eclipse tools
>>>> - Simple servlet and JSP applications
>>>> - Web applications
>>>> - EJB applications
>>>> - Security applications
>>>> - Web services applications
>>>> - Client applications
>>>> - ...
>>>>
>>>> - Deployment
>>>> - Deployer tool
>>>> - Deployment plans
>>>> - Deploying applications
>>>> - Deploying configurations/resources
>>>>
>>>> - Security
>>>> - Implementation overview
>>>> - Authentication
>>>> - Authorization
>>>> - Security modules
>>>> - Security realms
>>>> - Enabling SSL
>>>> - Programatic security
>>>> - Enabling security for applications
>>>> - LDAP
>>>>
>>>> - Applications migration
>>>>
>>>> - Performance and high availability
>>>> - Scalability
>>>> - Clustering
>>>>
>>>> - Hints and Tips
>>>>
>>>> - Troubleshooting
>>>>
>>>> - Sample applications
>>>>
>>>> - Other interesting resources
>>>> - Wiki SandBox
>>>> - People
>>>>
>>>>
>>>> I know I'm missing a lot but still wanted to give this first step.
>>>>
>>>> I'm sure with a better structure we can get more people easily
>>>> invovled on both, producing and consuming, documentation.
>>>>
>>>> Thank you all.
>>>>
>>>>
>>>> Cheers!
>>>> Hernan
>>>>
>>>
>>>
>>
>
Re: Wiki reorganization proposal
Posted by John Sisson <js...@apache.org>.
Hi Hernan,
I hope you don't feel that I don't want the wiki restructured, I just
think we should discuss what the wiki should be used for and how we
should deliver documentation for release x of Geronimo, accomodating
future requirements.
IMHO, Geronimo for a large proportion of users is only as good as its
documentation, which needs a rethink. Look forward to an interesting
discussion.
Others please chime in.
Comments inline below..
Regards,
John
Hernan Cunico wrote:
> Hi John,
>
> It will be very hard to keep updated all the documentation as new
> branches/releases come available. See comments inline
>
> Cheers!
> Hernan
>
>
> John Sisson wrote:
>
>> Hi Hernan,
>>
>> The suggested layout sounds fine to me. This is long overdue and is
>> an opportunity to remove/move/fix documentation that no longer matches
>> what has been implemented.
>>
>> My main concern with the use of the Wiki for documentation is that the
>> Wiki content isn't versioned to match Geronimo releases.
>
>
> wiki should not be versioned the same way Geronimo is. I would say, wiki
> should keep the pace of mayor milestones (M1, M5, V1...)
>
>>
>> For example, if you go to the page about building Geronimo with
>> eclipse and try using that with M4 you will have problems as the
>> documentation relies upon changes since M4.
>
>
> Maybe a commmon header for all docs stating versions used would address
> this issue.
Are you saying we have a different version of each document for each
version?
We should be able to have an easily accessible archive of doco for a
particular version of Geronimo. A user who adopts 1.0 should be able to
access the documentation for it (without it being polluted with updates
from later releases that are not relevant to 1.0) for at least a few years.
>
> ... These are the versions used for this doc, other versions have not
> been tested and may not work...
IMHO, wording like that in documentation normally wouldn't cut it in
commercial software. I think we are lacking a thought out strategy on
documentation. Sure there will be a few books that will be released on
Geronimo, but I don't think we should be relying upon them for
documentation. Will they be able to put updated versions of these books
with at the same time we put out a new geronimo release?
I view the wiki as a place that users can contribute notes or tips on
Geronimo usage that should eventually be fed into formal (printable as a
manual) documentation that is associated with each release.
>
>>
>> There have been other pages that have comments about what version they
>> are applicable to (e.g. for M4 do this, but for M5 do that), but a
>> user reading documentation for M5 doesn't want to have to skip all the
>> bits about M4 for example.
>
>
> I agree, I don't think it will be a good solution having a doc covering
> topic "A" and having having multiple entries to explain the same
> procedure for M4, M5, V1, ...
We need a solution for this issue. Can others chime in here with
suggestions?
>
>>
>> Is it possible to easily branch/copy the Wiki documentation when we do
>> a release? For example, for the 1.0 release a branch of the Wiki is
>> done so that the 1.0 documentation is easily accessible and can be
>> updated if needed after 1.0 is released.
>
>
> Creating a new V1 branch for the wiki will imply not just to "copy" some
> of the already available documentation but verifying each doc for
> accuracy and compatibility with V1. Sort of "V1 Certified" instructions.
>
> I would say this process should not be automatic, it would require a
> thorough reviewing of all the existing documentation.
>
I agree that it would require reviewing. I am hoping that if we come up
with a structured manual, when code changes are made, if there is an
impact to the documentation then the developer will make the appropriate
documentation changes. Other projects do this, why shouldn't we?
Currently I think it is hard to find parts of the wiki that need
updating when code changes are made, since it isn't structured in a way
that is easy to find the related doco.
>>
>> An issue I can see with branching/copying the Wiki content for each
>> release is that some users may update the doco in the branch, but not
>> the main doco that will be used for the next release.
>
>
> Yup, this wil be an additional issue.
>
> Maybe we should create an entry (I wouldn't call them branches as they
> would be more like the "release" type, main docs.) for M4, one for M5
> and one for the upcoming versions. We have some M4 and M5 docs today, I
> would suggest to separate the docs by version/milestone and focus on
> finishing M5, have this milestone as complete as possible creating the
> foundation for V1 doc.
>
This sounds like it is heading in the right direction, but doesn't solve
the printable manual option. Think a year or two down the track.. I
don't think the documentation will be small, so printing documentation
page by page does not sound appropriate. I think we need to be able to
print a PDF with the full bookmarks/hyperlinking etc (like the Derby doco).
>>
>> I like Wikis, except for the problem described above. I can only see
>> this problem getting worse as more releases are shipped.
>>
>> An alternative is to develop the main documentation under svn control
>> (the Derby project does this), but that would mean updates would have
>> to be submitted as patches. Derby's doco can be easily generated as a
>> PDF with bookmarks etc, which is great for offline or printing.
>
>
> Not sure if submitting updated as patches would be an issue. What is not
> clear to me is svn. Isn't a version control alrady in place for the
> documentation?
AFAIK, it is date versioned, but the wiki doesn't natively support
branches of documentation and tagging of releases. How easy is it to
make a copy of all M5 doco for the basis of M6 doco in the wiki? Any
wiki admin gurus here?
>
> It would be great to have a better "Show diff" functionality so you not
> only know there is a new version, but also know what's changed.
AFAIK, you can do diffs in the wiki now (may not be easy for those
unfamiliar with wikis to use).
>
>>
>> Maybe IBM be interested in taking a similar approach with the
>> documentation as Derby (contributing docs and resources for docs and
>> using it as a basis of their commercial product docs), as far as I can
>> tell, the Cloudscape doco is based on the open source Derby doco?
>
>
> Not sure what you mean!?
>
The Derby printed documentation is not from a wiki, AFAIK, they use DITA
(Darwin Informatation Typing Architecture) sourced XML documentation
that can be converted to both PDF and HTML book/files formats using
Apache FOP.
They have 6 manuals that have been produced using this.
http://db.apache.org/derby/manuals/dita.html
AFAIK, IBM's Cloudscape's documentation is based upon the documentation
contributed to Derby. Derby is probably not the best example since when
the documentation was initially contributed by IBM it was pretty much
complete, since they contributed what was the Cloudscape documentation
(please correct me if I am wrong).
I was wondering whether IBM or any other ISV that is considering
producing their own documentation for products derived from Geronimo
consider whether there would be benefits in contributing Geronimo
documentation to the Apache Geronimo project and use that as a base of
their customised documentation. Maybe we should speak with the Derby
project and ask for their experiences with their current documentation
processes.
>>
>> No harm in asking :-) ?
>>
>> Regards,
>>
>> John
>>
>> Hernan Cunico wrote:
>>
>>> Hi All,
>>> Independently of whether we will ever move wiki to confluence or not
>>> (there is a lot of discussion on this) still the Apache wiki needs
>>> some serious reorganization today.
>>>
>>> I think it should be restructured into something easier to browse,
>>> making a stronger focus on the Geronimo documentation. We could have
>>> sections at the bottom (sort of Appendixes) for all non-documentation
>>> related topics (people, contests, etc).
>>>
>>> This is the content as it is today:
>>>
>>> About
>>> Logo Contest
>>> Downloads
>>> Documentation
>>> Mailing Lists
>>> Issue Tracking
>>> Related Sites
>>> Project Status & Management
>>> Developer Information
>>> ObjectWeb Collaboration
>>> People
>>> Wiki Sand Box
>>>
>>>
>>> Most of this information is either redundant on the
>>> geronimo.apache.org front page or not relevant (like "Related sites").
>>>
>>> My suggestion is to provide a logical flow, from "the generic" to
>>> "the specific". Start with a "Project overview", then go with the
>>> "Geronimo architecture" and continue with a breakdown of that
>>> architecture, ...
>>>
>>> The structure I propose may look like a TOC for a book but, dreaming
>>> about a perfect world, it would be great if Geronimo can have a sound
>>> starting point for our documentation. I see other wiki-like sites and
>>> are a lot more organized.
>>>
>>> Here is my proposed content for the wiki:
>>>
>>> - Apache Geronimo project overview
>>> - About ASF
>>> - Licensing
>>>
>>> - Architecture
>>> - GBeans
>>> - Geronimo kernel
>>> - Naming
>>> - Tomcat
>>> - Jetty
>>> - Derby
>>> - Axis
>>> - TranQL
>>> - OpenEJB
>>> - MX4J
>>> - ActiveMQ
>>> - ApacheDS
>>> - ...
>>>
>>> - Installation
>>> - Platforms supported
>>> - Hardware and software prerequisites
>>> - Getting the source code
>>> - Build from the source
>>> - Installation
>>>
>>> - Administration
>>> - Tools
>>> start and stop services/servers, deployer.jar, etc
>>> - Geronimo Web Console
>>> - Configure resources
>>> - JavaMail
>>> - Database
>>> - ...
>>> - Logging
>>> - Backup and recovery
>>> - Maintenance
>>>
>>> - Development
>>> - Eclipse tools
>>> - Simple servlet and JSP applications
>>> - Web applications
>>> - EJB applications
>>> - Security applications
>>> - Web services applications
>>> - Client applications
>>> - ...
>>>
>>> - Deployment
>>> - Deployer tool
>>> - Deployment plans
>>> - Deploying applications
>>> - Deploying configurations/resources
>>>
>>> - Security
>>> - Implementation overview
>>> - Authentication
>>> - Authorization
>>> - Security modules
>>> - Security realms
>>> - Enabling SSL
>>> - Programatic security
>>> - Enabling security for applications
>>> - LDAP
>>>
>>> - Applications migration
>>>
>>> - Performance and high availability
>>> - Scalability
>>> - Clustering
>>>
>>> - Hints and Tips
>>>
>>> - Troubleshooting
>>>
>>> - Sample applications
>>>
>>> - Other interesting resources
>>> - Wiki SandBox
>>> - People
>>>
>>>
>>> I know I'm missing a lot but still wanted to give this first step.
>>>
>>> I'm sure with a better structure we can get more people easily
>>> invovled on both, producing and consuming, documentation.
>>>
>>> Thank you all.
>>>
>>>
>>> Cheers!
>>> Hernan
>>>
>>
>>
>
Re: Wiki reorganization proposal
Posted by Hernan Cunico <hc...@gmail.com>.
Hi John,
It will be very hard to keep updated all the documentation as new
branches/releases come available. See comments inline
Cheers!
Hernan
John Sisson wrote:
> Hi Hernan,
>
> The suggested layout sounds fine to me. This is long overdue and is an
> opportunity to remove/move/fix documentation that no longer matches what
> has been implemented.
>
> My main concern with the use of the Wiki for documentation is that the
> Wiki content isn't versioned to match Geronimo releases.
wiki should not be versioned the same way Geronimo is. I would say, wiki
should keep the pace of mayor milestones (M1, M5, V1...)
>
> For example, if you go to the page about building Geronimo with eclipse
> and try using that with M4 you will have problems as the documentation
> relies upon changes since M4.
Maybe a commmon header for all docs stating versions used would address
this issue.
... These are the versions used for this doc, other versions have not
been tested and may not work...
>
> There have been other pages that have comments about what version they
> are applicable to (e.g. for M4 do this, but for M5 do that), but a user
> reading documentation for M5 doesn't want to have to skip all the bits
> about M4 for example.
I agree, I don't think it will be a good solution having a doc covering
topic "A" and having having multiple entries to explain the same
procedure for M4, M5, V1, ...
>
> Is it possible to easily branch/copy the Wiki documentation when we do a
> release? For example, for the 1.0 release a branch of the Wiki is done
> so that the 1.0 documentation is easily accessible and can be updated if
> needed after 1.0 is released.
Creating a new V1 branch for the wiki will imply not just to "copy" some
of the already available documentation but verifying each doc for
accuracy and compatibility with V1. Sort of "V1 Certified" instructions.
I would say this process should not be automatic, it would require a
thorough reviewing of all the existing documentation.
>
> An issue I can see with branching/copying the Wiki content for each
> release is that some users may update the doco in the branch, but not
> the main doco that will be used for the next release.
Yup, this wil be an additional issue.
Maybe we should create an entry (I wouldn't call them branches as they
would be more like the "release" type, main docs.) for M4, one for M5
and one for the upcoming versions. We have some M4 and M5 docs today, I
would suggest to separate the docs by version/milestone and focus on
finishing M5, have this milestone as complete as possible creating the
foundation for V1 doc.
>
> I like Wikis, except for the problem described above. I can only see
> this problem getting worse as more releases are shipped.
>
> An alternative is to develop the main documentation under svn control
> (the Derby project does this), but that would mean updates would have to
> be submitted as patches. Derby's doco can be easily generated as a PDF
> with bookmarks etc, which is great for offline or printing.
Not sure if submitting updated as patches would be an issue. What is not
clear to me is svn. Isn't a version control alrady in place for the
documentation?
It would be great to have a better "Show diff" functionality so you not
only know there is a new version, but also know what's changed.
>
> Maybe IBM be interested in taking a similar approach with the
> documentation as Derby (contributing docs and resources for docs and
> using it as a basis of their commercial product docs), as far as I can
> tell, the Cloudscape doco is based on the open source Derby doco?
Not sure what you mean!?
>
> No harm in asking :-) ?
>
> Regards,
>
> John
>
> Hernan Cunico wrote:
>
>> Hi All,
>> Independently of whether we will ever move wiki to confluence or not
>> (there is a lot of discussion on this) still the Apache wiki needs
>> some serious reorganization today.
>>
>> I think it should be restructured into something easier to browse,
>> making a stronger focus on the Geronimo documentation. We could have
>> sections at the bottom (sort of Appendixes) for all non-documentation
>> related topics (people, contests, etc).
>>
>> This is the content as it is today:
>>
>> About
>> Logo Contest
>> Downloads
>> Documentation
>> Mailing Lists
>> Issue Tracking
>> Related Sites
>> Project Status & Management
>> Developer Information
>> ObjectWeb Collaboration
>> People
>> Wiki Sand Box
>>
>>
>> Most of this information is either redundant on the
>> geronimo.apache.org front page or not relevant (like "Related sites").
>>
>> My suggestion is to provide a logical flow, from "the generic" to "the
>> specific". Start with a "Project overview", then go with the
>> "Geronimo architecture" and continue with a breakdown of that
>> architecture, ...
>>
>> The structure I propose may look like a TOC for a book but, dreaming
>> about a perfect world, it would be great if Geronimo can have a sound
>> starting point for our documentation. I see other wiki-like sites and
>> are a lot more organized.
>>
>> Here is my proposed content for the wiki:
>>
>> - Apache Geronimo project overview
>> - About ASF
>> - Licensing
>>
>> - Architecture
>> - GBeans
>> - Geronimo kernel
>> - Naming
>> - Tomcat
>> - Jetty
>> - Derby
>> - Axis
>> - TranQL
>> - OpenEJB
>> - MX4J
>> - ActiveMQ
>> - ApacheDS
>> - ...
>>
>> - Installation
>> - Platforms supported
>> - Hardware and software prerequisites
>> - Getting the source code
>> - Build from the source
>> - Installation
>>
>> - Administration
>> - Tools
>> start and stop services/servers, deployer.jar, etc
>> - Geronimo Web Console
>> - Configure resources
>> - JavaMail
>> - Database
>> - ...
>> - Logging
>> - Backup and recovery
>> - Maintenance
>>
>> - Development
>> - Eclipse tools
>> - Simple servlet and JSP applications
>> - Web applications
>> - EJB applications
>> - Security applications
>> - Web services applications
>> - Client applications
>> - ...
>>
>> - Deployment
>> - Deployer tool
>> - Deployment plans
>> - Deploying applications
>> - Deploying configurations/resources
>>
>> - Security
>> - Implementation overview
>> - Authentication
>> - Authorization
>> - Security modules
>> - Security realms
>> - Enabling SSL
>> - Programatic security
>> - Enabling security for applications
>> - LDAP
>>
>> - Applications migration
>>
>> - Performance and high availability
>> - Scalability
>> - Clustering
>>
>> - Hints and Tips
>>
>> - Troubleshooting
>>
>> - Sample applications
>>
>> - Other interesting resources
>> - Wiki SandBox
>> - People
>>
>>
>> I know I'm missing a lot but still wanted to give this first step.
>>
>> I'm sure with a better structure we can get more people easily
>> invovled on both, producing and consuming, documentation.
>>
>> Thank you all.
>>
>>
>> Cheers!
>> Hernan
>>
>
>
Re: Wiki reorganization proposal
Posted by David Blevins <da...@visi.com>.
On Nov 1, 2005, at 8:27 PM, Rodent of Unusual Size wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> John Sisson wrote:
>>
>> My main concern with the use of the Wiki for documentation is that
>> the
>> Wiki content isn't versioned to match Geronimo releases.
>>
>
[snip]
>> An alternative is to develop the main documentation under svn control
>> (the Derby project does this), but that would mean updates would
>> have to
>> be submitted as patches. Derby's doco can be easily generated as
>> a PDF
>> with bookmarks etc, which is great for offline or printing.
>>
>
> Perhaps some mix would be good, such as a weekly checkin to
> svn of any changes to the wiki. Of course, then there's
> the issue of format compatibility. Do the wikis in use
> provide for XML exports? If so, a little glue should be
> able to automatically manage the conversion and checkin.
> The major problems I see with that is that the who-changed-what
> accountability is lost (unless a change to the wiki can
> be included in the export as an XML entity that can be used
> to identify the changer in svn), and that changes made
> between checkpoints don't get recorded.
>
I've cranked my brain on this one for awhile as OpenEJB now uses
confluence for documentation rather than generating html from xml
stored in cvs as we did before.
XML importing and exporting is possible in confluence, as well as
html and pdf exports (no import for those, though). As a couple
releases ago, they also have the ability to have "listeners" or
something that you can set up to be executed when pages are changed,
added, removed, etc. So, the most aggressive approach I can think of
is that we could setup a listener that exports the entire page and
checks it into svn. Some less aggressive version of that is possible
too.
As far as versioning, the best i can think of would be to have a
Confluence Space per svn branch. So a GERONIMO-X space for each
release branch under geronimo/branches/. Using Tomcat as an example
as we don't have branches yet, that'd be something like TOMCAT-4,
TOMCAT-50 and TOMCAT-55. You could even start a new space by
exporting from the previous major version's space, creating a new
space, then importing to the new space. If you export aggressively,
you can start a new Space from what's in svn.
Anyway, I haven't solved the problem completely but thats a high
level dump of what's in my brain in regards to import/export, source
control, and versioning.
-David
Re: Wiki reorganization proposal
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hernan Cunico wrote:
> Hi All,
> It seems like we all agree that versioning is extremely important
> although still not too clear to me what would be the versioning strategy.
I think there are two parts to it:
1. Accountability: Who changed what and when (hopefully with a
log message for the 'why').
2. Tying version-specific docco versions to the appropriate code
versions -- e.g., having one version tag that will get the code
and the docco for it in one step.
Beyond that, whatever works best for the project. :-)
- --
#ken P-)}
Ken Coar, Sanagendamgagwedweinini http://Ken.Coar.Org/
Author, developer, opinionist http://Apache-Server.Com/
"Millennium hand and shrimp!"
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (MingW32)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org
iQCVAwUBQ2vW2ZrNPMCpn3XdAQJHYgP/fsecqtRvyXe55vS9YV1LU6OlcX1w8E5q
4b0xKDVQ3ZBTvqkHh+SIeOC8KSDYj32YWnQPBUnsUn4OCBQShMmhTO3rLPlWjmRa
ujsVs+4z5MslKcyaCZ8FwSbZt14BnCpQZPWhe+1AdenkJ2YguIcZLSRDxV0jXv9t
dxlnd+v6jCM=
=SE67
-----END PGP SIGNATURE-----
Re: Wiki reorganization proposal
Posted by "Geir Magnusson Jr." <ge...@apache.org>.
On Nov 3, 2005, at 9:28 AM, Hernan Cunico wrote:
> Hi All,
> It seems like we all agree that versioning is extremely important
> although still not too clear to me what would be the versioning
> strategy.
>
with conventional documentation, where it's part of the project SVN
or CVS tree, it's really easy - when you cut a branch for a release,
you are also including the documentation.
> Still regarding to documentation and equally important is where to
> place the documentation. Apache wiki and Confluence are 50/50. I
> believe having the documentation all spread out across several
> places and formats is as bad as not having documentation. I
> personally think Confluence is more flexible (export to other
> formats), has better formating and more user friendly. Should we
> propose voting to have this issue addressed?
>
Voting won't change the fact that a wiki (MoinMoin|Confluence) is a
collaboration tool :)
My preference would be to *not* use a wiki, be it MoinMoin or
Confluence, for project documentation (maybe use Confluence as an
editing tool if it could export a useful format that could be
consumed by other renderers?).
> I have not seen many comments back on the reorganized structure
> itself. I would really like to see some more interaction there.
>
> Last but not least, should we start creating one major section for
> each major release (M4, M5, ...) on the wiki (or confluence)? This
> would be the first step forward in the reorganization.
>
Well, that's what doing docs in the project get you - there is a
natural progression of versions, as they get "carried along" with the
code version.
geir
> Cheers!
> Hernan
>
> Rodent of Unusual Size wrote:
>
>> -----BEGIN PGP SIGNED MESSAGE-----
>> Hash: SHA1
>> John Sisson wrote:
>>
>>> The suggested layout sounds fine to me. This is long overdue and
>>> is an
>>> opportunity to remove/move/fix documentation that no longer
>>> matches what
>>> has been implemented.
>>>
>>> My main concern with the use of the Wiki for documentation is
>>> that the
>>> Wiki content isn't versioned to match Geronimo releases.
>>>
>> I think that's pretty significant. Documentation needs to be
>> versioned allong with the code. Just as you can say 'this is
>> the state of the code as of tag-or-date X' you need to be
>> able to locate the corresponding documentation (regardless
>> of how well it has kept up with the code).
>> Wikis historically have been a collaboration tool, not a
>> documentation tool. Working together on docco in a wiki
>> is great and can speed things up enormously -- but it
>> needs to get integrated into the SVN repository periodically
>> for versioning and history retention.
>>
>>> An alternative is to develop the main documentation under svn
>>> control
>>> (the Derby project does this), but that would mean updates would
>>> have to
>>> be submitted as patches. Derby's doco can be easily generated as
>>> a PDF
>>> with bookmarks etc, which is great for offline or printing.
>>>
>> The patch model is used a lot, and it has the advantage of
>> handling the docco the same way the code is. However, it
>> doesn't lend itself to quick fixes of typos or contributions
>> by non-developers. Wikis are great for that sort of thing,
>> but have the problems you've already pointed out.
>> Perhaps some mix would be good, such as a weekly checkin to
>> svn of any changes to the wiki. Of course, then there's
>> the issue of format compatibility. Do the wikis in use
>> provide for XML exports? If so, a little glue should be
>> able to automatically manage the conversion and checkin.
>> The major problems I see with that is that the who-changed-what
>> accountability is lost (unless a change to the wiki can
>> be included in the export as an XML entity that can be used
>> to identify the changer in svn), and that changes made
>> between checkpoints don't get recorded.
>> There are lots of docco models in use out there. There's
>> the patch model which is used by Derby and the httpd
>> project; there's the user-comments-get-periodically-rolled-in
>> model that PHP uses; there's the wiki-only method, and probably
>> lots of others. I think the documentation should be considered
>> as much a product of the Geronimo project as the code, and
>> should be treated with the same care and attention to
>> versioning, history, and accountability.
>> My US$0.02.
>> - --
>> #ken P-)}
>> Ken Coar, Sanagendamgagwedweinini http://Ken.Coar.Org/
>> Author, developer, opinionist http://Apache-Server.Com/
>> "Millennium hand and shrimp!"
>> -----BEGIN PGP SIGNATURE-----
>> Version: GnuPG v1.2.4 (MingW32)
>> Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org
>> iQCVAwUBQ2hAKJrNPMCpn3XdAQJTkgQAzqd9n9viIJKEmIR31rsbkv5+6YyN+9Nd
>> 4cxDpJDoz037ZIZ/wo8XrKughZlltgcedECEDvOd/XQ4jTdSFS0OhVK2FRwpTIsH
>> Novl7V1Z/3p7Gb9MT6NlEhbKSn/RrCw0296fKNbLo1kz/+Db2r6B3WYJ8TpoeJri
>> BXv+kYkfJT4=
>> =VPrR
>> -----END PGP SIGNATURE-----
>
--
Geir Magnusson Jr +1-203-665-6437
geirm@apache.org
Re: Wiki reorganization proposal
Posted by Hernan Cunico <hc...@gmail.com>.
Hi All,
It seems like we all agree that versioning is extremely important
although still not too clear to me what would be the versioning strategy.
Still regarding to documentation and equally important is where to place
the documentation. Apache wiki and Confluence are 50/50. I believe
having the documentation all spread out across several places and
formats is as bad as not having documentation. I personally think
Confluence is more flexible (export to other formats), has better
formating and more user friendly. Should we propose voting to have this
issue addressed?
I have not seen many comments back on the reorganized structure itself.
I would really like to see some more interaction there.
Last but not least, should we start creating one major section for each
major release (M4, M5, ...) on the wiki (or confluence)? This would be
the first step forward in the reorganization.
Cheers!
Hernan
Rodent of Unusual Size wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> John Sisson wrote:
>
>>The suggested layout sounds fine to me. This is long overdue and is an
>>opportunity to remove/move/fix documentation that no longer matches what
>>has been implemented.
>>
>>My main concern with the use of the Wiki for documentation is that the
>>Wiki content isn't versioned to match Geronimo releases.
>
>
> I think that's pretty significant. Documentation needs to be
> versioned allong with the code. Just as you can say 'this is
> the state of the code as of tag-or-date X' you need to be
> able to locate the corresponding documentation (regardless
> of how well it has kept up with the code).
>
> Wikis historically have been a collaboration tool, not a
> documentation tool. Working together on docco in a wiki
> is great and can speed things up enormously -- but it
> needs to get integrated into the SVN repository periodically
> for versioning and history retention.
>
>
>>An alternative is to develop the main documentation under svn control
>>(the Derby project does this), but that would mean updates would have to
>>be submitted as patches. Derby's doco can be easily generated as a PDF
>>with bookmarks etc, which is great for offline or printing.
>
>
> The patch model is used a lot, and it has the advantage of
> handling the docco the same way the code is. However, it
> doesn't lend itself to quick fixes of typos or contributions
> by non-developers. Wikis are great for that sort of thing,
> but have the problems you've already pointed out.
>
> Perhaps some mix would be good, such as a weekly checkin to
> svn of any changes to the wiki. Of course, then there's
> the issue of format compatibility. Do the wikis in use
> provide for XML exports? If so, a little glue should be
> able to automatically manage the conversion and checkin.
> The major problems I see with that is that the who-changed-what
> accountability is lost (unless a change to the wiki can
> be included in the export as an XML entity that can be used
> to identify the changer in svn), and that changes made
> between checkpoints don't get recorded.
>
> There are lots of docco models in use out there. There's
> the patch model which is used by Derby and the httpd
> project; there's the user-comments-get-periodically-rolled-in
> model that PHP uses; there's the wiki-only method, and probably
> lots of others. I think the documentation should be considered
> as much a product of the Geronimo project as the code, and
> should be treated with the same care and attention to
> versioning, history, and accountability.
>
> My US$0.02.
> - --
> #ken P-)}
>
> Ken Coar, Sanagendamgagwedweinini http://Ken.Coar.Org/
> Author, developer, opinionist http://Apache-Server.Com/
>
> "Millennium hand and shrimp!"
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.2.4 (MingW32)
> Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org
>
> iQCVAwUBQ2hAKJrNPMCpn3XdAQJTkgQAzqd9n9viIJKEmIR31rsbkv5+6YyN+9Nd
> 4cxDpJDoz037ZIZ/wo8XrKughZlltgcedECEDvOd/XQ4jTdSFS0OhVK2FRwpTIsH
> Novl7V1Z/3p7Gb9MT6NlEhbKSn/RrCw0296fKNbLo1kz/+Db2r6B3WYJ8TpoeJri
> BXv+kYkfJT4=
> =VPrR
> -----END PGP SIGNATURE-----
>
>
Re: Wiki reorganization proposal
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
John Sisson wrote:
>
> The suggested layout sounds fine to me. This is long overdue and is an
> opportunity to remove/move/fix documentation that no longer matches what
> has been implemented.
>
> My main concern with the use of the Wiki for documentation is that the
> Wiki content isn't versioned to match Geronimo releases.
I think that's pretty significant. Documentation needs to be
versioned allong with the code. Just as you can say 'this is
the state of the code as of tag-or-date X' you need to be
able to locate the corresponding documentation (regardless
of how well it has kept up with the code).
Wikis historically have been a collaboration tool, not a
documentation tool. Working together on docco in a wiki
is great and can speed things up enormously -- but it
needs to get integrated into the SVN repository periodically
for versioning and history retention.
> An alternative is to develop the main documentation under svn control
> (the Derby project does this), but that would mean updates would have to
> be submitted as patches. Derby's doco can be easily generated as a PDF
> with bookmarks etc, which is great for offline or printing.
The patch model is used a lot, and it has the advantage of
handling the docco the same way the code is. However, it
doesn't lend itself to quick fixes of typos or contributions
by non-developers. Wikis are great for that sort of thing,
but have the problems you've already pointed out.
Perhaps some mix would be good, such as a weekly checkin to
svn of any changes to the wiki. Of course, then there's
the issue of format compatibility. Do the wikis in use
provide for XML exports? If so, a little glue should be
able to automatically manage the conversion and checkin.
The major problems I see with that is that the who-changed-what
accountability is lost (unless a change to the wiki can
be included in the export as an XML entity that can be used
to identify the changer in svn), and that changes made
between checkpoints don't get recorded.
There are lots of docco models in use out there. There's
the patch model which is used by Derby and the httpd
project; there's the user-comments-get-periodically-rolled-in
model that PHP uses; there's the wiki-only method, and probably
lots of others. I think the documentation should be considered
as much a product of the Geronimo project as the code, and
should be treated with the same care and attention to
versioning, history, and accountability.
My US$0.02.
- --
#ken P-)}
Ken Coar, Sanagendamgagwedweinini http://Ken.Coar.Org/
Author, developer, opinionist http://Apache-Server.Com/
"Millennium hand and shrimp!"
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (MingW32)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org
iQCVAwUBQ2hAKJrNPMCpn3XdAQJTkgQAzqd9n9viIJKEmIR31rsbkv5+6YyN+9Nd
4cxDpJDoz037ZIZ/wo8XrKughZlltgcedECEDvOd/XQ4jTdSFS0OhVK2FRwpTIsH
Novl7V1Z/3p7Gb9MT6NlEhbKSn/RrCw0296fKNbLo1kz/+Db2r6B3WYJ8TpoeJri
BXv+kYkfJT4=
=VPrR
-----END PGP SIGNATURE-----
Re: Wiki reorganization proposal
Posted by John Sisson <js...@apache.org>.
Hi Hernan,
The suggested layout sounds fine to me. This is long overdue and is an
opportunity to remove/move/fix documentation that no longer matches what
has been implemented.
My main concern with the use of the Wiki for documentation is that the
Wiki content isn't versioned to match Geronimo releases.
For example, if you go to the page about building Geronimo with eclipse
and try using that with M4 you will have problems as the documentation
relies upon changes since M4.
There have been other pages that have comments about what version they
are applicable to (e.g. for M4 do this, but for M5 do that), but a user
reading documentation for M5 doesn't want to have to skip all the bits
about M4 for example.
Is it possible to easily branch/copy the Wiki documentation when we do a
release? For example, for the 1.0 release a branch of the Wiki is done
so that the 1.0 documentation is easily accessible and can be updated if
needed after 1.0 is released.
An issue I can see with branching/copying the Wiki content for each
release is that some users may update the doco in the branch, but not
the main doco that will be used for the next release.
I like Wikis, except for the problem described above. I can only see
this problem getting worse as more releases are shipped.
An alternative is to develop the main documentation under svn control
(the Derby project does this), but that would mean updates would have to
be submitted as patches. Derby's doco can be easily generated as a PDF
with bookmarks etc, which is great for offline or printing.
Maybe IBM be interested in taking a similar approach with the
documentation as Derby (contributing docs and resources for docs and
using it as a basis of their commercial product docs), as far as I can
tell, the Cloudscape doco is based on the open source Derby doco?
No harm in asking :-) ?
Regards,
John
Hernan Cunico wrote:
> Hi All,
> Independently of whether we will ever move wiki to confluence or not
> (there is a lot of discussion on this) still the Apache wiki needs some
> serious reorganization today.
>
> I think it should be restructured into something easier to browse,
> making a stronger focus on the Geronimo documentation. We could have
> sections at the bottom (sort of Appendixes) for all non-documentation
> related topics (people, contests, etc).
>
> This is the content as it is today:
>
> About
> Logo Contest
> Downloads
> Documentation
> Mailing Lists
> Issue Tracking
> Related Sites
> Project Status & Management
> Developer Information
> ObjectWeb Collaboration
> People
> Wiki Sand Box
>
>
> Most of this information is either redundant on the geronimo.apache.org
> front page or not relevant (like "Related sites").
>
> My suggestion is to provide a logical flow, from "the generic" to "the
> specific". Start with a "Project overview", then go with the "Geronimo
> architecture" and continue with a breakdown of that architecture, ...
>
> The structure I propose may look like a TOC for a book but, dreaming
> about a perfect world, it would be great if Geronimo can have a sound
> starting point for our documentation. I see other wiki-like sites and
> are a lot more organized.
>
> Here is my proposed content for the wiki:
>
> - Apache Geronimo project overview
> - About ASF
> - Licensing
>
> - Architecture
> - GBeans
> - Geronimo kernel
> - Naming
> - Tomcat
> - Jetty
> - Derby
> - Axis
> - TranQL
> - OpenEJB
> - MX4J
> - ActiveMQ
> - ApacheDS
> - ...
>
> - Installation
> - Platforms supported
> - Hardware and software prerequisites
> - Getting the source code
> - Build from the source
> - Installation
>
> - Administration
> - Tools
> start and stop services/servers, deployer.jar, etc
> - Geronimo Web Console
> - Configure resources
> - JavaMail
> - Database
> - ...
> - Logging
> - Backup and recovery
> - Maintenance
>
> - Development
> - Eclipse tools
> - Simple servlet and JSP applications
> - Web applications
> - EJB applications
> - Security applications
> - Web services applications
> - Client applications
> - ...
>
> - Deployment
> - Deployer tool
> - Deployment plans
> - Deploying applications
> - Deploying configurations/resources
>
> - Security
> - Implementation overview
> - Authentication
> - Authorization
> - Security modules
> - Security realms
> - Enabling SSL
> - Programatic security
> - Enabling security for applications
> - LDAP
>
> - Applications migration
>
> - Performance and high availability
> - Scalability
> - Clustering
>
> - Hints and Tips
>
> - Troubleshooting
>
> - Sample applications
>
> - Other interesting resources
> - Wiki SandBox
> - People
>
>
> I know I'm missing a lot but still wanted to give this first step.
>
> I'm sure with a better structure we can get more people easily invovled
> on both, producing and consuming, documentation.
>
> Thank you all.
>
>
> Cheers!
> Hernan
>
Wiki reorganization proposal
Posted by Hernan Cunico <hc...@gmail.com>.
Hi All,
Independently of whether we will ever move wiki to confluence or not
(there is a lot of discussion on this) still the Apache wiki needs some
serious reorganization today.
I think it should be restructured into something easier to browse,
making a stronger focus on the Geronimo documentation. We could have
sections at the bottom (sort of Appendixes) for all non-documentation
related topics (people, contests, etc).
This is the content as it is today:
About
Logo Contest
Downloads
Documentation
Mailing Lists
Issue Tracking
Related Sites
Project Status & Management
Developer Information
ObjectWeb Collaboration
People
Wiki Sand Box
Most of this information is either redundant on the geronimo.apache.org
front page or not relevant (like "Related sites").
My suggestion is to provide a logical flow, from "the generic" to "the
specific". Start with a "Project overview", then go with the "Geronimo
architecture" and continue with a breakdown of that architecture, ...
The structure I propose may look like a TOC for a book but, dreaming
about a perfect world, it would be great if Geronimo can have a sound
starting point for our documentation. I see other wiki-like sites and
are a lot more organized.
Here is my proposed content for the wiki:
- Apache Geronimo project overview
- About ASF
- Licensing
- Architecture
- GBeans
- Geronimo kernel
- Naming
- Tomcat
- Jetty
- Derby
- Axis
- TranQL
- OpenEJB
- MX4J
- ActiveMQ
- ApacheDS
- ...
- Installation
- Platforms supported
- Hardware and software prerequisites
- Getting the source code
- Build from the source
- Installation
- Administration
- Tools
start and stop services/servers, deployer.jar, etc
- Geronimo Web Console
- Configure resources
- JavaMail
- Database
- ...
- Logging
- Backup and recovery
- Maintenance
- Development
- Eclipse tools
- Simple servlet and JSP applications
- Web applications
- EJB applications
- Security applications
- Web services applications
- Client applications
- ...
- Deployment
- Deployer tool
- Deployment plans
- Deploying applications
- Deploying configurations/resources
- Security
- Implementation overview
- Authentication
- Authorization
- Security modules
- Security realms
- Enabling SSL
- Programatic security
- Enabling security for applications
- LDAP
- Applications migration
- Performance and high availability
- Scalability
- Clustering
- Hints and Tips
- Troubleshooting
- Sample applications
- Other interesting resources
- Wiki SandBox
- People
I know I'm missing a lot but still wanted to give this first step.
I'm sure with a better structure we can get more people easily invovled
on both, producing and consuming, documentation.
Thank you all.
Cheers!
Hernan
Re: New Solaris Zones
Posted by "Geir Magnusson Jr." <ge...@apache.org>.
Great. That's two :)
Once I'm in, I'll get you guys in, and we'll take it from there.
geir
On Oct 28, 2005, at 4:51 PM, Jeff Genender wrote:
> I think DB and I could help out ;-)
>
>
>> I think we should give all committers accounts. As for sudo access,
>> I think we should give it to a couple of committers that have a good
>> unix background and are willing to help. I'm willing to help, but my
>> unix skills are weak. I'm personally hoping that David Blevins
>> (hint) and Jeff Genender volunteer (hint) as both of them have mad
>> unix admin skills :)
>>
>> I think we should apply the same rules to the geronimo-tck zone
>> except that only NDA signers would get access.
>>
>> -dain
>>
>> On Oct 28, 2005, at 12:41 PM, Geir Magnusson Jr. wrote:
>>
>>
>>> The solaris zones for Geronimo are being created, one for general
>>> project use and one for tck use.
>>>
>>> How shall we administer them?
>>>
>>> geir
>>>
>>> --
>>> Geir Magnusson Jr +1-203-665-6437
>>> geirm@apache.org
>>>
>>>
>>>
>>
>>
>
>
--
Geir Magnusson Jr +1-203-665-6437
geirm@apache.org
Re: New Solaris Zones
Posted by Jeff Genender <jg...@savoirtech.com>.
I think DB and I could help out ;-)
> I think we should give all committers accounts. As for sudo access,
> I think we should give it to a couple of committers that have a good
> unix background and are willing to help. I'm willing to help, but my
> unix skills are weak. I'm personally hoping that David Blevins
> (hint) and Jeff Genender volunteer (hint) as both of them have mad
> unix admin skills :)
>
> I think we should apply the same rules to the geronimo-tck zone
> except that only NDA signers would get access.
>
> -dain
>
> On Oct 28, 2005, at 12:41 PM, Geir Magnusson Jr. wrote:
>
>> The solaris zones for Geronimo are being created, one for general
>> project use and one for tck use.
>>
>> How shall we administer them?
>>
>> geir
>>
>> --
>> Geir Magnusson Jr +1-203-665-6437
>> geirm@apache.org
>>
>>
>
Re: New Solaris Zones
Posted by Dain Sundstrom <da...@iq80.com>.
I think we should give all committers accounts. As for sudo access,
I think we should give it to a couple of committers that have a good
unix background and are willing to help. I'm willing to help, but my
unix skills are weak. I'm personally hoping that David Blevins
(hint) and Jeff Genender volunteer (hint) as both of them have mad
unix admin skills :)
I think we should apply the same rules to the geronimo-tck zone
except that only NDA signers would get access.
-dain
On Oct 28, 2005, at 12:41 PM, Geir Magnusson Jr. wrote:
> The solaris zones for Geronimo are being created, one for general
> project use and one for tck use.
>
> How shall we administer them?
>
> geir
>
> --
> Geir Magnusson Jr +1-203-665-6437
> geirm@apache.org
>
>