geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From John Sisson <jsis...@apache.org>
Subject Re: Wiki reorganization proposal
Date Tue, 01 Nov 2005 07:22:14 GMT
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
>>>
>>
>>
> 

Mime
View raw message