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
