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
