geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hernan Cunico <hcun...@gmail.com>
Subject Re: Wiki reorganization proposal
Date Mon, 31 Oct 2005 16:48:29 GMT
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
>>
> 
> 

Mime
View raw message