[docs] legacy tab for 2.1 documents

[Bertrand Delacretaz <bd...@apache.org>]

I have added a "legacy" tab to the new docs, as a temporary storage 
place for existing 2.1 documents.

You can see some examples under the "legacy" tab at 
http://brutus.apache.org/docs/publish/cocoon-2-2/ provided the site has 
been regenerated in the meantime (supposed to happen every few hours), 
or by running Forrest 0.6 locally as explained in 
http://wiki.apache.org/cocoon/22NewDocumentsGeneration

The idea would be to work as follows to review the 2.1 docs and move 
the good parts to the new docs structure:

1. Copy all existing 2.1 documents under 
src/documentation/src/content/xdocs, giving them names starting with 
c21_ as for the few examples that I did. Update the site.xml 
accordingly.

2. For each of these docs, add a meta.xml file containing 
<source>legacy.21</source> so that they are identified as unreviewed 
legacy documents in the published site.

3. Review each document and either promote it to a 2.2 document, reuse 
some of its content in a new document or decide not to keep it. I'd 
suggest keeping as little content as possible as official 2.2 docs, so 
that we're able to maintain it properly with our limited resources (but 
that's another story).

4. When moving parts of a document, use a <moved> element as in 
c21_introduction/content_en.xdoc (the site:concepts.html link there 
doesn't work yet though).

Having all the 2.1 docs in this legacy tab helps make sure that we 
don't lose any document in the process, and allows us to work in small 
increments, tracked in SVN, to reorganize and improve the docs.

WDYT?

-Bertrand

Re: [docs] legacy tab for 2.1 documents

[Bertrand Delacretaz <bd...@apache.org>]

Le 28 mars 05, à 22:28, Bertrand Delacretaz a écrit :
> ...You can see some examples under the "legacy" tab at 
> http://brutus.apache.org/docs/publish/cocoon-2-2/ ..

Sorry wrong link, the generated docs are at 
http://brutus.apache.org/docs/build/cocoon-2-2/

-Bertrand

Re: [docs] legacy tab for 2.1 documents

[Bertrand Delacretaz <bd...@apache.org>]

Le 29 mars 05, à 08:54, Reinhard Poetz a écrit :
> ...Well, your suggestion would be helpful but means some work. I don't 
> have much time ATM that I can spend on moving over docs (it's not 
> forgotten and even better if others jump in!!!), but if you can do the 
> integration into the new Forrest repo, I'm +1!..

I should be able to do it later this week. It's mostly scriptable work, 
shouldn't take too long.

> ...If you have time for the integration of the legacy docs, please use 
> the documents in my home directory (Cocoon committers can read/write 
> them using SCP) as they are the merged versions of 2.1 *and* old 2.2 
> legacy docs. I've just upoaded the site.xml (see 
> http://people.apache.org/~reinhard/2.2/site.xml)...

Ok, I'll take them there, thanks for the instructions!

-Bertrand

Re: [docs] legacy tab for 2.1 documents

[Reinhard Poetz <re...@apache.org>]

Bertrand Delacretaz wrote:
> I have added a "legacy" tab to the new docs, as a temporary storage 
> place for existing 2.1 documents.
> 
> You can see some examples under the "legacy" tab at 
> http://brutus.apache.org/docs/publish/cocoon-2-2/ provided the site has 
> been regenerated in the meantime (supposed to happen every few hours), 
> or by running Forrest 0.6 locally as explained in 
> http://wiki.apache.org/cocoon/22NewDocumentsGeneration
> 
> The idea would be to work as follows to review the 2.1 docs and move the 
> good parts to the new docs structure:
> 
> 1. Copy all existing 2.1 documents under 
> src/documentation/src/content/xdocs, giving them names starting with 
> c21_ as for the few examples that I did. Update the site.xml accordingly.
> 
> 2. For each of these docs, add a meta.xml file containing 
> <source>legacy.21</source> so that they are identified as unreviewed 
> legacy documents in the published site.
> 
> 3. Review each document and either promote it to a 2.2 document, reuse 
> some of its content in a new document or decide not to keep it. I'd 
> suggest keeping as little content as possible as official 2.2 docs, so 
> that we're able to maintain it properly with our limited resources (but 
> that's another story).
> 
> 4. When moving parts of a document, use a <moved> element as in 
> c21_introduction/content_en.xdoc (the site:concepts.html link there 
> doesn't work yet though).
> 
> Having all the 2.1 docs in this legacy tab helps make sure that we don't 
> lose any document in the process, and allows us to work in small 
> increments, tracked in SVN, to reorganize and improve the docs.
> 
> WDYT?

Betrand, many thanks for your work on the docs so far!

In http://wiki.apache.org/cocoon/22NewDocuments there is a list of all legacy 
documents. The list contains links to the raw HTML version of the document which 
is available at http://people.apache.org/~reinhard/2.2/**.
After updating a document a comment should be added to the Wiki document and it 
could be deleted as the group rights of http://people.apache.org/~reinhard/2.2/ 
where set to 'cocoon'.

Well, your suggestion would be helpful but means some work. I don't have much 
time ATM that I can spend on moving over docs (it's not forgotten and even 
better if others jump in!!!), but if you can do the integration into the new 
Forrest repo, I'm +1!

If you have time for the integration of the legacy docs, please use the 
documents in my home directory (Cocoon committers can read/write them using SCP) 
as they are the merged versions of 2.1 *and* old 2.2 legacy docs. I've just 
upoaded the site.xml (see http://people.apache.org/~reinhard/2.2/site.xml).

IIUC the tasks left are:

  - download http://people.apache.org/~reinhard/2.2/site.xml
  - use SCP and download all HTML docs from my home directory
  - write a script that transfers all documents into the new "directory-per
    document" structure
  - update site.xml (http://people.apache.org/~reinhard/2.2/site.xml could ´
    be helpful as starting point)

HTH

-- 
Reinhard Pötz           Independent Consultant, Trainer & (IT)-Coach 

{Software Engineering, Open Source, Web Applications, Apache Cocoon}

                                        web(log): http://www.poetz.cc
--------------------------------------------------------------------