Re: Wiki reorganization proposal

[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

[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
>>>>
>>>
>>>
>>
>