2.2 Documentation

[Daniel Fagerstrom <da...@nada.kth.se>]

was: Re: Planning 2.2

Ezkovich Glen wrote:
...

> I agree. But if you release today, then no one except those that have  
> touched those things or followed the developer list will know what  
> those features are much less how to use them.

A 2.2 M1 is for the benefit of the community and early adapters rather 
than for a broad audience. It is for channeling community focus and 
energy, which will cretate value for a broader audience after a while.

Neither the less we need to start a 2.2 Documentation effort:

> Point me in the right direction, give me a tentative release date and  
> I will write up some documentation. Best offer I can give you today.

Thanks for the offer. Can't give you a tentative release date, but at 
least some pointers:

We need a 2.2 branch of our documentation (maybe there allready is one?)

Documentation of (please everyone, provide relevant links to mail and 
other documentation):

> - ECM++
> - Virtual sitemap components

(not particullary mature yet, but start with 
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=111316710610638&w=2 and 
ask on the list)

> - blocks (sitemap blocks, exposing blocks)

Ongoing work, but the "sitemap aspect" 
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=111791016006393&w=2 is 
based on a large amount of community driven design, so it might be 
worthwhile to start documenting. The "component aspect", and the OSGi 
part need more work and discussion.

> - per sitemap reloading classloader (for dev)
> - reworked property management
> - Spring integration (Spring block)
> - possible to listen to sitemap events
> - refactoring of Javaflow (uses now the commons-javaflow project which
>   was started by Thorsten)
> - introduction of CTemplate (refactoring of JXTemplate in 2.1.x)

It should be completely back compatible with the original JXTG, but can 
also be used in non flow environment. Leszek have added some features, 
can you give links to relevant mails please.

                          --- o0o ---

I guess, collecting relevant links to mail and current documentation 
snippets in the Wiki or in Daisy, would be a good first step.

WDYT?

/Daniel

Re: 2.2 Documentation

[hepabolu <he...@gmail.com>]

Bruno Dumon wrote:
> Are you sure this is unnecessary? The current setup shares the same
> documents in the new docs and the legacy docs. Thus when the new docs
> are updated, refactored, retired etc, this influences the legacy docs
> too. This was fine as long as the legacy docs served exactly for this
> purpose, but now the legacy docs have turned into the official 2.1.8
> documentation. If we don't make a branch for 2.1.8, there's no way the
> 2.1.x docs can still be produced and maintained in the future.

Hmm. Currently there is so much "crap" (i.e. outdated documents or 
documents describing ideas rather than real implementations) among the 
documentation in the legacydocs collection, that I'm all for retiring 
documents in that collection or slightly modifying the ones that are 
still mostly valid.
That would improve the 2.1.8 documentation as well as the 2.2 documentation.

OTOH you're right that over time, the documentation of the 2.1 branche 
would change too, which is unwanted.

My suggestion is a temporary solution, a kind of transition phase when 
2.1.X is becoming "obsolete" and 2.2 is taking over. Once the 
"official" 2.2 is released, we should create a branch to ensure that 
2.1.X is "frozen". At that time, we might also decide that there will be 
no more changes in the 2.1.X documentation at which point they will be 
removed from Daisy entirely and the only copy resides in the SVN repository.

Bye, Helma

Re: 2.2 Documentation

[Bruno Dumon <br...@outerthought.org>]

On Wed, 2005-11-23 at 12:58 +0100, hepabolu wrote:
> Regarding the documentation of 2.2:
> 
> Let me first give you some Daisy background to clarify things, before I 
> explain what I have in mind.
> Note that this is the quick & dirty explanation. The Outerthought boys 
> can give a much more detailed overview.
> 
> Daisy supports "sites" (the already mentioned Legacy docs and 
> Documentation) and "collections". A collection is merely a set of 
> documents and a site can be considered as a view on one or more 
> collections. That's what is currently the case in our Daisy setup in the 
> zones:
> 
> Collection "legacydocs" contains all documentation as it was present in 
> the xdocs of BRANCH_2.1.X. Collection "documentation" contains all new 
> documents that are written in Daisy.
> Bruno has marked documents part of "legacydocs" with a two line red 
> warning at the top of the document. You can see this when you open such 
> a page in Daisy.
> 
> There are already two sites in Daisy: Legacy docs and Documentation. 
> Both use documents from both collections.
> 
> My idea was this:
> 
> I've used Legacy docs site to recreate the "old" cocoon.apache.org site 
> as best as possible. If this is not enough, a little bit of work needs 
> to be done.
> This site will be restricted to the 2.1 branch. Since Cocoon 2.1 is 
> frozen when it comes to new features, I suggest that the documentation 
> is only updated when some blatant errors or typos are found.
> 
> For the 2.2 version please use the Documentation site. That's where new 
> documentation is supposed to be entered. This site also contains links 
> to all available documents in the legacydocs collection, see the last 
> line in the navigation bar.
> This is added for convenience: if you find documentation in the 
> legacydocs that is still valid for the 2.2 version, just move the 
> documentation from the legacydocs collection to the documentation 
> collection. This has no impact on the documentation in the Legacydocs site.
> I know it's possible that a document resides in both collections, but I 
> want to end up with a collection of legacydocs that holds information 
> that is either completely outdated or only valid for the 2.1 branch.
> 
> I know we can make branches in Daisy, but at the moment I don't think 
> this is necessary. I'd rather use that feature when we move from 2.2 to 3.0.

Are you sure this is unnecessary? The current setup shares the same
documents in the new docs and the legacy docs. Thus when the new docs
are updated, refactored, retired etc, this influences the legacy docs
too. This was fine as long as the legacy docs served exactly for this
purpose, but now the legacy docs have turned into the official 2.1.8
documentation. If we don't make a branch for 2.1.8, there's no way the
2.1.x docs can still be produced and maintained in the future.

-- 
Bruno Dumon                             http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org                          bruno@apache.org

Re: 2.2 Documentation

[hepabolu <he...@gmail.com>]

Regarding the documentation of 2.2:

Let me first give you some Daisy background to clarify things, before I 
explain what I have in mind.
Note that this is the quick & dirty explanation. The Outerthought boys 
can give a much more detailed overview.

Daisy supports "sites" (the already mentioned Legacy docs and 
Documentation) and "collections". A collection is merely a set of 
documents and a site can be considered as a view on one or more 
collections. That's what is currently the case in our Daisy setup in the 
zones:

Collection "legacydocs" contains all documentation as it was present in 
the xdocs of BRANCH_2.1.X. Collection "documentation" contains all new 
documents that are written in Daisy.
Bruno has marked documents part of "legacydocs" with a two line red 
warning at the top of the document. You can see this when you open such 
a page in Daisy.

There are already two sites in Daisy: Legacy docs and Documentation. 
Both use documents from both collections.

My idea was this:

I've used Legacy docs site to recreate the "old" cocoon.apache.org site 
as best as possible. If this is not enough, a little bit of work needs 
to be done.
This site will be restricted to the 2.1 branch. Since Cocoon 2.1 is 
frozen when it comes to new features, I suggest that the documentation 
is only updated when some blatant errors or typos are found.

For the 2.2 version please use the Documentation site. That's where new 
documentation is supposed to be entered. This site also contains links 
to all available documents in the legacydocs collection, see the last 
line in the navigation bar.
This is added for convenience: if you find documentation in the 
legacydocs that is still valid for the 2.2 version, just move the 
documentation from the legacydocs collection to the documentation 
collection. This has no impact on the documentation in the Legacydocs site.
I know it's possible that a document resides in both collections, but I 
want to end up with a collection of legacydocs that holds information 
that is either completely outdated or only valid for the 2.1 branch.

I know we can make branches in Daisy, but at the moment I don't think 
this is necessary. I'd rather use that feature when we move from 2.2 to 3.0.

In summary:
- don't use the legacydocs site

- new documents, about new features of Cocoon 2.2, go into the 
Documentation site. They are part of the documentation collection 
(automatically if you have the Documentation site open) and they are of 
type "Document" (not SimpleDocument).

- if the documentation you want to write is already present in the 
legacydocs and is valid for both versions, move the document to the 
"documentation" collection:
    - select the document, select "edit" (you have to be logged in), 
select the "Misc" tab and make sure the "selected" list contains only 
"documentation".

- if the documentation you want to write is already present in the 
legacydocs, but is not entirely correct:
    - are the changes you want to add also valid for 2.1?
       - yes: go ahead, change the document and move it from the 
legacydocs to documentation.

       - no: are the changes minor?
             - yes: add one or more "notes" (paragraphs marked Note) 
that explain the differences between 2.1 and 2.2 and move the document 
from the legacydocs to documentation.

             - no: create a new document in the documentation collection 
and write the information as if the legacydocs document didn't exist.

- if you find documentation in the legacydocs that is outdated for both 
2.1 and 2.2, then retire the document (Misc tab, under the Options section)

- if you find documentation in the wiki that is useful:
    - copy the information to a Daisy document and finish this
    - mark the wiki page with a message that the information is added to 
the "official" Cocoon documentation.

- if there is information in the mailing lists that is useful:
    - copy the information and elaborate it, turn it into a coherent 
piece of information.
    - if necessary, add the links to the relevant messages (each Daisy 
document has a separate links section that ends up at the bottom of the 
page). PLEASE DON'T SIMPLY REFER TO THE MAIL MESSAGES.

Most of this info is also written on the home page of the Cocoon 
Documentation site in Daisy:

http://cocoon.zones.apache.org/daisy/documentation/659.html

If the above is clear, I'll update that page to reflect this information.

Bye, Helma