Documentation structure

[Grzegorz Kossakowski <gr...@tuffmail.com>]

Reinhard Poetz napisał(a):
> Thanks for the offer. You're doc-editor now. This means that you can
> change documents but not publish them which is reserved for committers
> only.
>
Thanks. Before I start messing around I would like to be sure I
understand all the principles and aims.
You've said:
> That's my fault. "documentation" was our first attempt but didn't fit
> our main goal of having separate deployment units. I will add a
> warning message to the sites overview.
>
> Last year I started to restructure our documentation so that each
> deployment unit has its own documentation - these are all the
> 'cdocs-*' sites/collections. The 'cdocs' site gives an overview of all
> available documents. You can find detailed information about the
> documentation system at
> http://cocoon.zones.apache.org/daisy/cdocs/1201.html. HTH.
>
'documentation' collection is now deprecated so we should refine all
valuable pieces from it and move them to the suitable collections,
right? Then, eventually, it would be deleted to clear things out?

Another question arises about 'Quickstart to Cocoon-2.2 with Maven' [1].
Instruction included there should be meant for those who want to do some
Cocoon development not Application development using Cocoon, right? Now,
if one wants to patch code of some block (let's say Forms), she must
checkout whole trunk source code and install all artifacts in snapshot
version. Is it going to change? I mean, will blocks in the future depend
only on released versions (seems quite impossible for me)? I ask about
this because it's necessary to know if one is going to update docs for
contributors.

Also, should documents belong to different collections at the same time?
Suppose we have tutorial that covers usage of few blocks (template,
forms, flowscript). Where should it be put into?


[1] http://cocoon.zones.apache.org/daisy/documentation/g1/798.html

-- 
Grzegorz Kossakowski

Re: Documentation structure

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

Grzegorz Kossakowski wrote:
> Reinhard Poetz napisał(a):
>> Thanks for the offer. You're doc-editor now. This means that you can
>> change documents but not publish them which is reserved for committers
>> only.
>>
> Thanks. Before I start messing around I would like to be sure I
> understand all the principles and aims.
> You've said:
>> That's my fault. "documentation" was our first attempt but didn't fit
>> our main goal of having separate deployment units. I will add a
>> warning message to the sites overview.
>>
>> Last year I started to restructure our documentation so that each
>> deployment unit has its own documentation - these are all the
>> 'cdocs-*' sites/collections. The 'cdocs' site gives an overview of all
>> available documents. You can find detailed information about the
>> documentation system at
>> http://cocoon.zones.apache.org/daisy/cdocs/1201.html. HTH.
>>
> 'documentation' collection is now deprecated so we should refine all
> valuable pieces from it and move them to the suitable collections,
> right? 

yes

> Then, eventually, it would be deleted to clear things out?

yes

> Another question arises about 'Quickstart to Cocoon-2.2 with Maven' [1].
> Instruction included there should be meant for those who want to do some
> Cocoon development not Application development using Cocoon, right?

yes, see the warning message at the top.

> Now,
> if one wants to patch code of some block (let's say Forms), she must
> checkout whole trunk source code and install all artifacts in snapshot
> version. Is it going to change? I mean, will blocks in the future depend
> only on released versions (seems quite impossible for me)?

Not at all, but we need some stable fundament for this. After having final 
releases of our core components, we can think about it.

> I ask about
> this because it's necessary to know if one is going to update docs for
> contributors.

sorry, don't understand this.

> 
> Also, should documents belong to different collections at the same time?

no

> Suppose we have tutorial that covers usage of few blocks (template,
> forms, flowscript). Where should it be put into?

for now put them into cdocs-site-main into the "Getting started" section. In the 
(desireable) case of having too many of those tutorial docs, we can think about 
some better structure or location.

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

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

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

		
___________________________________________________________ 
Telefonate ohne weitere Kosten vom PC zum PC: http://messenger.yahoo.de