You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Steven Noels <st...@outerthought.org> on 2003/03/24 07:31:39 UTC
[vote] micro-decision for docs: creation of cocoon-docs CVS module
In order to get one little step closer to the 'new' document
infrastructure, many of us seek clarity whether we should move docs to a
separate CVS module or not. The benefits and downfalls are largely
known, so let's vote on this and get this issue cleared.
My own personal bias: don't forget the different Cocoon _versions_ are
now stored in separate modules, too.
Please cast your vote:
[ ] creation of cocoon-docs module
[ ] docs should stay in src/documentation of the code tree module(s)
Cheers,
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Stefano Mazzocchi <st...@apache.org>.
Steven Noels wrote:
> In order to get one little step closer to the 'new' document
> infrastructure, many of us seek clarity whether we should move docs to a
> separate CVS module or not. The benefits and downfalls are largely
> known, so let's vote on this and get this issue cleared.
>
> My own personal bias: don't forget the different Cocoon _versions_ are
> now stored in separate modules, too.
>
> Please cast your vote:
>
> [ ] creation of cocoon-docs module
> [ X ] docs should stay in src/documentation of the code tree module(s)
I don't see the need to separate docs into another CVS module and it
might well be potentially harmful for the perception of two different
groups, one that does code and one that does docs. Perception that has
been harming the documentation process a lot.
Stefano.
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Stefano Mazzocchi <st...@apache.org>.
Andrew Savory wrote:
> Committer vote not even finished and *already* I'm causing trouble ;-)
The more people helps me making a mess, the more I won't get blamed alone :)
You got my vote exactly for that :)
Stefano.
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS
module
Posted by Andrew Savory <an...@luminas.co.uk>.
Hi,
On Mon, 24 Mar 2003, Steven Noels wrote:
> > (where +1 for docs in src/documentation is for static docs)
>
> Could you expand on 'static' docs, please?
Yes, I mean generated - ie the HTML output of running Cocoon/Forrest
against the cocoon-docs CVS, so that anyone that's grabbed a copy of the
cocoon distribution has a pre-generated set of documentation to work from
without having to worry about getting Cocoon up and running first. This is
important (especially in light of Stefano's suggestion to drop the 'war'
distribution) because:
- offline workers don't have the luxury of accessing the Cocoon site to
get help;
- not everyone will have the skill to get Cocoon running / debugged (for
whatever reason);
- not everyone will want to have Cocoon running in order to read the docs;
- not everyone will know how to / realise how to "build docs".
These are all gut feelings, and I must admit I'm not entirely delighted at
the idea of a big bundle of static content shipping with Cocoon, but at
the same time, it seems like a trivial thing to do to make users' lives
easier.
Also, small point of order to everyone: can we keep an eye on
cross-posting between cocoon-dev and cocoon-docs, please? It defeats the
point of a separate docs list if we have to track discussions across both.
(Yes, I know this issue really affects cocoon-dev too, but a notification
there about the vote should do to attract interested parties...)
Committer vote not even finished and *already* I'm causing trouble ;-)
Andrew.
--
Andrew Savory Email: andrew@luminas.co.uk
Managing Director Tel: +44 (0)870 741 6658
Luminas Internet Applications Fax: +44 (0)700 598 1135
This is not an official statement or order. Web: www.luminas.co.uk
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Steven Noels <st...@outerthought.org>.
On 24/03/2003 8:29 Andrew Savory wrote:
> Not a committer, but:
Nearly there! ;-)
> On Mon, 24 Mar 2003, Steven Noels wrote:
>
>
>>Please cast your vote:
>>
>> [+1] creation of cocoon-docs module
>> [+1] docs should stay in src/documentation of the code tree module(s)
>
>
> (where +1 for docs in src/documentation is for static docs)
Could you expand on 'static' docs, please?
I was lazy this morning, so I'm glad relevant points are iterated below.
> So, here it is: discussion on cocoon-docs repository.
>
> As I see it, there are the following pros/cons:
>
> PRO:
>
> 1) Keep all documentation in one place (rather than split across two
> repositories as now), optionally with tools required to build it. Keeps
> documentation concern separate from code.
>
> 2) Allows people to work on documentation without needing a copy of Cocoon
> CVS (which implies optional cocoon-doc-only committers, although I'm not
> sure if this is good/required). Focuses attention on documentation as an
> entity.
>
> 3) Allows merging of 2.0/2.1/... documentation into a single base (not
> possible if documentation is kept in version-specific code repository).
<agree/>
> CON:
>
> 1) Out of site, out of mind. If it is split, will developers forget to
> update the docs?
As I said, already the code repo is split across two modules, so anybody
working on both 2.0.x and 2.1 versions has already two sandboxes, adding
another one shouldn't be too hard.
> 2) If you checkout the code, you don't get a copy of the documentation.
People 'checking out' (= investigating) the code should download a
source distribution. We've been requiring people to live off CVS
checkouts already for too long. People 'CVS checking out' should not
mind checking out another module.
> In my mind, pro 3 is enough to swing it, but I'd like a solution to con 2
> as it worries me. Perhaps the answer to con 2 is to include the static
> snapshot not within cocoon-docs but within cocoon-2.0/cocoon-2.1? So then
> you get a copy of the software with a static copy of the docs, and can
> check out doc cvs if you want to build it dynamically?
Ah - 'static' == generated...?
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS
module
Posted by Andrew Savory <an...@luminas.co.uk>.
Not a committer, but:
On Mon, 24 Mar 2003, Steven Noels wrote:
> Please cast your vote:
>
> [+1] creation of cocoon-docs module
> [+1] docs should stay in src/documentation of the code tree module(s)
(where +1 for docs in src/documentation is for static docs)
I sent an email this morning that my stupid MTA bounced back to me.
Included it below as I think it's still relevant regardless of the vote,
and I'd like to hear what others think about the issue raised.
(I hope I get my attributions correct! Multiple snipping and shuffling
follows ...)
Diana Shannon wrote:
> How should we transition? How about:
>
> 2. Set up separate Cocoon docs repo(s)
> - decide what the repo will include (simply docs and/or tools)
> - copy both 2.1 and 2.0 docs and associated files into separate
> modules/branches/repos. Maintain "old" doc build capability, as
> currently functioning, in 2.1 and 2.0.
Jeff Turner wrote:
> having XML in a separate cocoon-docs module is likely to trigger
> the "out of sight, out of mind" syndrome.
Diana Shannon wrote:
> I hope this isn't true. I also believe it's an overgeneralization. We've
> had this debate a lot. I had the impression that consensus is moving
> toward supporting a single docs cvs.
On Mon, 24 Mar 2003, David Crossley wrote:
> We probably need to have a separate discussion on this topic
> of "separate repository for docs" to solve it once and for all.
So, here it is: discussion on cocoon-docs repository.
As I see it, there are the following pros/cons:
PRO:
1) Keep all documentation in one place (rather than split across two
repositories as now), optionally with tools required to build it. Keeps
documentation concern separate from code.
2) Allows people to work on documentation without needing a copy of Cocoon
CVS (which implies optional cocoon-doc-only committers, although I'm not
sure if this is good/required). Focuses attention on documentation as an
entity.
3) Allows merging of 2.0/2.1/... documentation into a single base (not
possible if documentation is kept in version-specific code repository).
CON:
1) Out of site, out of mind. If it is split, will developers forget to
update the docs?
2) If you checkout the code, you don't get a copy of the documentation.
In my mind, pro 3 is enough to swing it, but I'd like a solution to con 2
as it worries me. Perhaps the answer to con 2 is to include the static
snapshot not within cocoon-docs but within cocoon-2.0/cocoon-2.1? So then
you get a copy of the software with a static copy of the docs, and can
check out doc cvs if you want to build it dynamically?
Thoughts?
Andrew.
--
Andrew Savory Email: andrew@luminas.co.uk
Managing Director Tel: +44 (0)870 741 6658
Luminas Internet Applications Fax: +44 (0)700 598 1135
This is not an official statement or order. Web: www.luminas.co.uk
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Sylvain Wallez <sy...@anyware-tech.com>.
Steven Noels wrote:
> In order to get one little step closer to the 'new' document
> infrastructure, many of us seek clarity whether we should move docs to
> a separate CVS module or not. The benefits and downfalls are largely
> known, so let's vote on this and get this issue cleared.
>
> My own personal bias: don't forget the different Cocoon _versions_ are
> now stored in separate modules, too.
>
> Please cast your vote:
>
> [X] creation of cocoon-docs module
> [ ] docs should stay in src/documentation of the code tree module(s)
I don't clearly understand the second item : is it simply the negation
of the first one ?
To avoid to much disruption (we've seen recently how bad this is
perceived), I'm +1 too keep the docs in src/documentation until the new
cocoon-docs module is up to speed. This means that in the meantime,
src/documentation should be frozen : it stays there untouched until the
new system is ready. I prefer slightly outdated docs that no docs at all !
I also think Cocoon distros should include a static snapshot of the
docs. This means that the doc system should be able to identify
version-specific documents or even document parts to produce an adequate
documentation.
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module]
Posted by Vadim Gritsenko <va...@verizon.net>.
Sylvain Wallez wrote:
> Steven Noels wrote:
>
>> [ ] creation of cocoon-docs module: morrijr, shannon, stefano,
>> bdelacretaz
>> not sure because of comments: sylvain
>
+1
Vadim
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module]
Posted by Stefano Mazzocchi <st...@apache.org>.
Sylvain Wallez wrote:
> Steven Noels wrote:
>
>> (follow up to cocoon-docs please)
>>
>> On 24/03/2003 7:31 Steven Noels wrote:
>>
>>> In order to get one little step closer to the 'new' document
>>> infrastructure, many of us seek clarity whether we should move docs
>>> to a separate CVS module or not. The benefits and downfalls are
>>> largely known, so let's vote on this and get this issue cleared.
>>>
>>> My own personal bias: don't forget the different Cocoon _versions_
>>> are now stored in separate modules, too.
>>>
>>> Please cast your vote:
>>
>>
>>
>> results so far:
>>
>> [ ] creation of cocoon-docs module: morrijr, shannon, stefano,
>> bdelacretaz
>> not sure because of comments: sylvain
>
>
>
> In order to remove the "not sure" : I'm firmly +1 for a cocoon-docs module.
>
> The comments were about the transition period before the new doc system
> is fully operational, in which we should take care to still be able to
> build the "old" docs to avoid a "no-docs" period.
We are already able to build the docs using forrest. Try the following:
cvs checkout cocoon-2.1
cvs checkout xml-forrest
cd xml-forrest
./build.sh dist-shbat
cd ../cocoon-2.1
./build.sh forrest
they key is to have the two cvs modules living side by side and
preparing the shbat dist (what a stupid name, anyway) first.
Stefano.
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module]
Posted by Sylvain Wallez <sy...@anyware-tech.com>.
Steven Noels wrote:
> (follow up to cocoon-docs please)
>
> On 24/03/2003 7:31 Steven Noels wrote:
>
>> In order to get one little step closer to the 'new' document
>> infrastructure, many of us seek clarity whether we should move docs
>> to a separate CVS module or not. The benefits and downfalls are
>> largely known, so let's vote on this and get this issue cleared.
>>
>> My own personal bias: don't forget the different Cocoon _versions_
>> are now stored in separate modules, too.
>>
>> Please cast your vote:
>
>
> results so far:
>
> [ ] creation of cocoon-docs module: morrijr, shannon, stefano,
> bdelacretaz
> not sure because of comments: sylvain
In order to remove the "not sure" : I'm firmly +1 for a cocoon-docs module.
The comments were about the transition period before the new doc system
is fully operational, in which we should take care to still be able to
build the "old" docs to avoid a "no-docs" period.
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module]
Posted by Niclas Hedhman <ni...@hedhman.org>.
On Thursday 27 March 2003 21:48, Jeff Turner wrote:
> Nooooo.. not more voting! ;)
Can't voting be better automated, instead of a lot of +1 emails, that are hard
to count (does anyone ever count?).
Niclas
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module]
Posted by Steven Noels <st...@outerthought.org>.
On 27/03/2003 14:48 Jeff Turner wrote:
> Nooooo.. not more voting! ;)
>
> How about we just *try* cocoon-docs. If it turns out to be a
> sufficiently bad idea, scrap it.
>
> Sigh.. suppose we have to vote on that. Can't win either way ;)
Gee. I'll vote against voting. Does that help? ;-D
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module]
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Jeudi, 27 mars 2003, à 15:17 Europe/Zurich, Pier Fumagalli a écrit :
> ...
> +1 :-) Should I open the repo?
+1.
As I understand there are no risks associated with this, just need
indicate in the announcement that commits to this will affect
cocoon-2.1 too, so voting is probably not required for a "test phase"
IMHO.
-Bertrand
Re: tallying [Re: [vote] micro-decision for docs: creation of
cocoon-docs CVS module]
Posted by Pier Fumagalli <pi...@betaversion.org>.
"Jeff Turner" <je...@apache.org> wrote:
> How about we just *try* cocoon-docs. If it turns out to be a
> sufficiently bad idea, scrap it.
+1 :-) Should I open the repo?
Pier
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module]
Posted by Jeff Turner <je...@apache.org>.
On Thu, Mar 27, 2003 at 02:16:02PM +0100, Bertrand Delacretaz wrote:
> Le Jeudi, 27 mars 2003, à 13:52 Europe/Zurich, Diana Shannon a écrit :
>
> >...
> >I think a discussion intermixed with a vote changes the vote so that
> >people end up voting on different issues -- with no clear cut result.
>
> Agreed - in this particular case, the best thing might be to cancel the
> current vote and make a new proposal (taking into account the
> "cocoon-docs alias" stuff)?
> This would make sure everyone's on the same wavelength before voting.
Nooooo.. not more voting! ;)
How about we just *try* cocoon-docs. If it turns out to be a
sufficiently bad idea, scrap it.
Sigh.. suppose we have to vote on that. Can't win either way ;)
--Jeff
> Steven, you started the original vote, what do you think?
>
> -Bertrand
>
Re: tallying [Re: [vote] micro-decision for docs: creation of
cocoon-docs CVS module]
Posted by Pier Fumagalli <pi...@betaversion.org>.
"Bertrand Delacretaz" <bd...@codeconsult.ch> wrote:
> -Pier suggested [1] using a CVS alias to have cocoon-docs point to the
> src/docs directory of the current code repository (but I don't think he
> said how hard/easy/quick this is to implement).
Null brainer! :-)
Pier
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module]
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Jeudi, 27 mars 2003, à 14:31 Europe/Zurich, Steven Noels a écrit :
> ...It's good to see that the 'requirement' to vote adds some energy to
> the discussion, but then again, you, Diana & David are mostly right
> when suggesting that vote was premature and underspecified. I'm the
> hero of underspecification, but keep that silent. :-D
I don't want to speak for others but I thank you for starting the vote,
it lead to interesting discussions...
(ok, maybe starting it on both -dev and -docs was a suboptimal idea, it
might be better to just send an announcement of the vote to the other
list in such cases ;-)
I might be biased by my own understanding of the whole thing but here's
where I think we are:
-general agreement on the need for a separate cocoon-docs repository
-Pier suggested [1] using a CVS alias to have cocoon-docs point to the
src/docs directory of the current code repository (but I don't think he
said how hard/easy/quick this is to implement).
-I suggested [2] moving the alias to the new CVS when a release is done
(which was probably implicit in Pier's proposal).
So the proposal should probably be along the lines of "creating a
cocoon-docs repository that is an alias of cocoon-2.1/src/docs and
moving the alias to the new repository when a release is done".
-Bertrand
[1] http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=104853357923160&w=2
[2] http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=104867380029850&w=2
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module]
Posted by Steven Noels <st...@outerthought.org>.
On 27/03/2003 14:16 Bertrand Delacretaz wrote:
> Le Jeudi, 27 mars 2003, à 13:52 Europe/Zurich, Diana Shannon a écrit :
>
>> ...
>> I think a discussion intermixed with a vote changes the vote so that
>> people end up voting on different issues -- with no clear cut result.
>
>
> Agreed - in this particular case, the best thing might be to cancel the
> current vote and make a new proposal (taking into account the
> "cocoon-docs alias" stuff)?
> This would make sure everyone's on the same wavelength before voting.
>
> Steven, you started the original vote, what do you think?
It's good to see that the 'requirement' to vote adds some energy to the
discussion, but then again, you, Diana & David are mostly right when
suggesting that vote was premature and underspecified. I'm the hero of
underspecification, but keep that silent. :-D
Personally, I find it difficult to follow the current discussion, so if
somebody would be able to summarize (as a proposal), this will help (at
least stupid me ;-)
Cheers,
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module]
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, March 27, 2003, at 08:16 AM, Bertrand Delacretaz wrote:
> Agreed - in this particular case, the best thing might be to cancel the
> current vote and make a new proposal (taking into account the
> "cocoon-docs alias" stuff)?
Wasn't Pier going to experiment with this approach and report back? If
so, shouldn't we wait[1] for his feedback? Pier?
Diana
[1] There she goes again, using the #&!? word "wait" ;-)
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module]
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Jeudi, 27 mars 2003, à 13:52 Europe/Zurich, Diana Shannon a écrit :
> ...
> I think a discussion intermixed with a vote changes the vote so that
> people end up voting on different issues -- with no clear cut result.
Agreed - in this particular case, the best thing might be to cancel the
current vote and make a new proposal (taking into account the
"cocoon-docs alias" stuff)?
This would make sure everyone's on the same wavelength before voting.
Steven, you started the original vote, what do you think?
-Bertrand
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module]
Posted by Diana Shannon <sh...@apache.org>.
On Wednesday, March 26, 2003, at 10:52 PM, David Crossley wrote:
>>
>> Hm. Could be, although this particular subject has been discussed,
>> semi-proposed and whatnot already at some serious length in the
>> past, the usual circular discussion following suit hereafter.
>
> I only ever saw haphazard discussion, never a clear proposal,
> and then suddenly a vote. The discussion then had to happen
> mixed up with the vote. This approach does not seem to work.
I think a discussion intermixed with a vote changes the vote so that
people end up voting on different issues -- with no clear cut result.
Diana
Re: tallying [Re: [vote] micro-decision for docs: creation of
cocoon-docs CVS module]
Posted by David Crossley <cr...@indexgeo.com.au>.
Steven Noels wrote:
> David Crossley wrote:
<snip/>
> >
> > I think that the murkiness is a result of not having
> > a proposal and subsequent discussion before calling
> > a vote.
>
> Hm. Could be, although this particular subject has been discussed,
> semi-proposed and whatnot already at some serious length in the
> past, the usual circular discussion following suit hereafter.
I only ever saw haphazard discussion, never a clear proposal,
and then suddenly a vote. The discussion then had to happen
mixed up with the vote. This approach does not seem to work.
> IMHO, only you and Diana are feeling confident with the current
> documentation 'system' (please consider this to be a sincere
> compliment). Of course, this situation is wrong.
Actually, i do not feel at all confident (thanks for the compliment).
I have been keen to have an improved system for a long time.
> Therefore, I'm on a quest for a clean-sheet approach. I see two (!) main
> areas:
>
> - the website, with some general purpose info, and Cocoon primers
> - Cocoon documentation, which is a mix of serious hand-written
> reference material, and some generated stuff, which is properly
> versioned and closely attached to a certain release version - no more
> CVS syncing anymore.
I see that second item as still being published on the website.
> Sigh. I assume this is some pattern in (community?) development: "at a
> certain point in time, people will want to start from scratch in order
> to proceed, and the historical past is only a burden then". Or is it
> just my own laziness when it comes to proper refactoring?
Well i think that refactoring should "build upon" previous
work rather than "destroy and re-build". Starting from scratch
would be okay, as long as any old work that was still relevant
was built back in again. Often valuable work gets hidden in the
CVS Attic, perhaps with good intentions to bring it back during
second stage of refactoring. When it gets forgotten, then that
is a community killer.
--David
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module]
Posted by Steven Noels <st...@outerthought.org>.
On 26/03/2003 7:02 David Crossley wrote:
> I think that the murkiness is a result of not having
> a proposal and subsequent discussion before calling
> a vote.
Hm. Could be, although this particular subject has been discussed,
semi-proposed and whatnot already at some serious length in the past,
the usual circular dicussion following suit hereafter.
IMHO, only you and Diana are feeling confident with the current
documentation 'system' (please consider this to be a sincere
compliment). Of course, this situation is wrong.
Therefore, I'm on a quest for a clean-sheet approach. I see two (!) main
areas:
- the website, with some general purpose info, and Cocoon primers
- Cocoon documentation, which is a mix of serious hand-written
reference material, and some generated stuff, which is properly
versioned and closely attached to a certain release version - no more
CVS syncing anymore.
Sigh. I assume this is some pattern in (community?) development: "at a
certain point in time, people will want to start from scratch in order
to proceed, and the historical past is only a burden then". Or is it
just my own laziness when it comes to proper refactoring?
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: tallying [Re: [vote] micro-decision for docs: creation of
cocoon-docs CVS module]
Posted by David Crossley <cr...@indexgeo.com.au>.
Steven Noels wrote:
<snip/>
>
> Yep, this is quite some murky vote, and some tallying indeed does help.
I think that the murkiness is a result of not having
a proposal and subsequent discussion before calling
a vote.
--David
Re: tallying [Re: [vote] micro-decision for docs: creation of
cocoon-docs CVS module]
Posted by Pier Fumagalli <pi...@betaversion.org>.
On 24/3/03 8:41 pm, "Steven Noels" <st...@outerthought.org> wrote:
> IIRC, you can't alias a dir to a _dir_ of another module, at least that
> was what I was trying to do. Symlinking serverside will not work, I
> assume...?
Nope, alias wouldn't work, but symlink would (although I don't like them
"that much").
Pier
Re: tallying [Re: [vote] micro-decision for docs: creation of
cocoon-docs CVS module]
Posted by Pier Fumagalli <pi...@betaversion.org>.
On 24/3/03 8:41 pm, "Steven Noels" <st...@outerthought.org> wrote:
> IIRC, you can't alias a dir to a _dir_ of another module, at least that
> was what I was trying to do. Symlinking serverside will not work, I
> assume...?
Nope, alias wouldn't work, but symlink would (although I don't like them
"that much").
Pier
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module]
Posted by Steven Noels <st...@outerthought.org>.
On 24/03/2003 21:30 Pier Fumagalli wrote:
> Steven... I didn't say that the documentation should reside in the
> src/documentation... I lean (on the other hand) quite on the other side of
> the fence, because I know that if someone wants to have those docs in
> src/documentation, we can make this happen easily like the HTTP project does
> with its documentation... :-)
Oops - sorry :-)
Yep, this is quite some murky vote, and some tallying indeed does help.
I understood you the other way around, i.e. cocoon-docs being the cvs
module alias of src/documentation of cocoon-2x (yep, I forgot about CVS
aliasing, though I messed around already with it once)
The way I understand it now, maybe this setup might work:
cocoon-docs:
src\
documentation\
v20
v21
tools
cocoon-2x:
src\@documentation -> being an alias to module
cocoon-docs\src\documentation\v2x
IIRC, you can't alias a dir to a _dir_ of another module, at least that
was what I was trying to do. Symlinking serverside will not work, I
assume...?
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module]
Posted by Steven Noels <st...@outerthought.org>.
On 24/03/2003 21:30 Pier Fumagalli wrote:
> Steven... I didn't say that the documentation should reside in the
> src/documentation... I lean (on the other hand) quite on the other side of
> the fence, because I know that if someone wants to have those docs in
> src/documentation, we can make this happen easily like the HTTP project does
> with its documentation... :-)
Oops - sorry :-)
Yep, this is quite some murky vote, and some tallying indeed does help.
I understood you the other way around, i.e. cocoon-docs being the cvs
module alias of src/documentation of cocoon-2x (yep, I forgot about CVS
aliasing, though I messed around already with it once)
The way I understand it now, maybe this setup might work:
cocoon-docs:
src\
documentation\
v20
v21
tools
cocoon-2x:
src\@documentation -> being an alias to module
cocoon-docs\src\documentation\v2x
IIRC, you can't alias a dir to a _dir_ of another module, at least that
was what I was trying to do. Symlinking serverside will not work, I
assume...?
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: tallying [Re: [vote] micro-decision for docs: creation of
cocoon-docs CVS module]
Posted by Pier Fumagalli <pi...@betaversion.org>.
On 24/3/03 7:38 pm, "Steven Noels" <st...@outerthought.org> wrote:
> (follow up to cocoon-docs please)
>
> On 24/03/2003 7:31 Steven Noels wrote:
>
>> In order to get one little step closer to the 'new' document
>> infrastructure, many of us seek clarity whether we should move docs to a
>> separate CVS module or not. The benefits and downfalls are largely
>> known, so let's vote on this and get this issue cleared.
>>
>> My own personal bias: don't forget the different Cocoon _versions_ are
>> now stored in separate modules, too.
>>
>> Please cast your vote:
>
> results so far:
>
> [ ] creation of cocoon-docs module: morrijr, shannon, stefano,
> bdelacretaz
> not sure because of comments: sylvain
> not sure because of 0.x vote: haul
> not eligible but almost a committer: andrew
>
> [ ] docs should stay in src/documentation of the code tree
> module(s): jefft, nicolaken, pier, stephan
>
> ... which means we could use some more votes do establish genuine
> consensus...!
Steven... I didn't say that the documentation should reside in the
src/documentation... I lean (on the other hand) quite on the other side of
the fence, because I know that if someone wants to have those docs in
src/documentation, we can make this happen easily like the HTTP project does
with its documentation... :-)
Pier
Re: tallying [Re: [vote] micro-decision for docs: creation of
cocoon-docs CVS module]
Posted by Pier Fumagalli <pi...@betaversion.org>.
On 24/3/03 7:38 pm, "Steven Noels" <st...@outerthought.org> wrote:
> (follow up to cocoon-docs please)
>
> On 24/03/2003 7:31 Steven Noels wrote:
>
>> In order to get one little step closer to the 'new' document
>> infrastructure, many of us seek clarity whether we should move docs to a
>> separate CVS module or not. The benefits and downfalls are largely
>> known, so let's vote on this and get this issue cleared.
>>
>> My own personal bias: don't forget the different Cocoon _versions_ are
>> now stored in separate modules, too.
>>
>> Please cast your vote:
>
> results so far:
>
> [ ] creation of cocoon-docs module: morrijr, shannon, stefano,
> bdelacretaz
> not sure because of comments: sylvain
> not sure because of 0.x vote: haul
> not eligible but almost a committer: andrew
>
> [ ] docs should stay in src/documentation of the code tree
> module(s): jefft, nicolaken, pier, stephan
>
> ... which means we could use some more votes do establish genuine
> consensus...!
Steven... I didn't say that the documentation should reside in the
src/documentation... I lean (on the other hand) quite on the other side of
the fence, because I know that if someone wants to have those docs in
src/documentation, we can make this happen easily like the HTTP project does
with its documentation... :-)
Pier
tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module]
Posted by Steven Noels <st...@outerthought.org>.
(follow up to cocoon-docs please)
On 24/03/2003 7:31 Steven Noels wrote:
> In order to get one little step closer to the 'new' document
> infrastructure, many of us seek clarity whether we should move docs to a
> separate CVS module or not. The benefits and downfalls are largely
> known, so let's vote on this and get this issue cleared.
>
> My own personal bias: don't forget the different Cocoon _versions_ are
> now stored in separate modules, too.
>
> Please cast your vote:
results so far:
[ ] creation of cocoon-docs module: morrijr, shannon, stefano,
bdelacretaz
not sure because of comments: sylvain
not sure because of 0.x vote: haul
not eligible but almost a committer: andrew
[ ] docs should stay in src/documentation of the code tree
module(s): jefft, nicolaken, pier, stephan
... which means we could use some more votes do establish genuine
consensus...!
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Jeff Turner wrote, On 24/03/2003 10.13:
> On Mon, Mar 24, 2003 at 07:31:39AM +0100, Steven Noels wrote:
>
>>In order to get one little step closer to the 'new' document
>>infrastructure, many of us seek clarity whether we should move docs to a
>>separate CVS module or not. The benefits and downfalls are largely
>>known, so let's vote on this and get this issue cleared.
>>
>>My own personal bias: don't forget the different Cocoon _versions_ are
>>now stored in separate modules, too.
>>
>>Please cast your vote:
>>
>
> [ ] creation of cocoon-docs module
> [+1] docs should stay in src/documentation of the code tree module(s)
For me
[+1] docs should stay in src/documentation of the code tree module(s)
> Because:
>
> - With a separate cocoon-docs module, I don't see how the various
> code-related files (status.xml, jars.xml) are obtained.
>
> - Making a separate doc module kills outright any future efforts to
> generate docs directly from code (e.g. a component manual).
>
> - I think that by default, doc changes should only apply to one codebase
> (2.0 or 2.1). There are many differences that are *meant* to be there,
> that could get lost if 2.0 and 2.1 docs are generated from a common
> source.
I agree with all the above.
I want to remember that Avalon has decided to keep an avalon-site
module, but only for the *site*, not the documentation.
Is there a difference? Sure, we just forgot about it till now :->
The site keeps basic design point, the infos for the users
(contributing, mailing lists, etc), and basically anything that is not
related to product documentation.
I'd be +0 for that, but else the docs should be where the code is (and
javadocs are even nearer).
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Jeff Turner wrote, On 24/03/2003 10.13:
> On Mon, Mar 24, 2003 at 07:31:39AM +0100, Steven Noels wrote:
>
>>In order to get one little step closer to the 'new' document
>>infrastructure, many of us seek clarity whether we should move docs to a
>>separate CVS module or not. The benefits and downfalls are largely
>>known, so let's vote on this and get this issue cleared.
>>
>>My own personal bias: don't forget the different Cocoon _versions_ are
>>now stored in separate modules, too.
>>
>>Please cast your vote:
>>
>
> [ ] creation of cocoon-docs module
> [+1] docs should stay in src/documentation of the code tree module(s)
For me
[+1] docs should stay in src/documentation of the code tree module(s)
> Because:
>
> - With a separate cocoon-docs module, I don't see how the various
> code-related files (status.xml, jars.xml) are obtained.
>
> - Making a separate doc module kills outright any future efforts to
> generate docs directly from code (e.g. a component manual).
>
> - I think that by default, doc changes should only apply to one codebase
> (2.0 or 2.1). There are many differences that are *meant* to be there,
> that could get lost if 2.0 and 2.1 docs are generated from a common
> source.
I agree with all the above.
I want to remember that Avalon has decided to keep an avalon-site
module, but only for the *site*, not the documentation.
Is there a difference? Sure, we just forgot about it till now :->
The site keeps basic design point, the infos for the users
(contributing, mailing lists, etc), and basically anything that is not
related to product documentation.
I'd be +0 for that, but else the docs should be where the code is (and
javadocs are even nearer).
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Mercredi, 26 mars 2003, à 10:45 Europe/Zurich, Stefano Mazzocchi a
écrit :
> ....So, the proposal is not about forcing docu-oriented people as
> second-class citizens, but potentially allowing people (or services)
> that *request* or *need* to be docu-oriented-only to be able to be
> given karma like that...
Sounds good - a cocoon-docs CVS which is an alias to the "docs"
subdirectory of the current CVS offers what we need IMHO (judging from
the recent messages here an on cocoon-docs).
Also, I assume the alias would be moved when a new version is released,
so as to automatically freeze the current release's docs with the code
while still allowing them to be corrected later on if needed.
This would be transparent from the point of view of the cocoon-docs
repository, which is also an advantage if you're thinking CMS / webdav
access or whatever.
I'm +1 on this "cocoon-docs alias repository" thing.
-Bertrand
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Stefano Mazzocchi <st...@apache.org>.
David Crossley wrote:
> Stefano Mazzocchi wrote:
>
>>Pier Fumagalli wrote:
>
> <snip/>
>
>>>Folks, do you know that there's the possibility to alias certain subparts of
>>>a particular CVS repository from another repository?
>>>
>>>Like "cocoon-2.1/src/docs" can be stored in the "cocoon-docs" repository.
>>>
>>>Apache does it already with its httpd-docs repository, aliased to
>>>httpd-2.0/docs (or something like it)...
>>
>>Uh, that sounds *AWESOME*!
>>
>>Could it be possible, then, to restrict access of some committers only
>>to the doc module but have commits coming thru the *main* module land in
>>there as well?
>>
>>That would solve all issues at once, I guess.
>>
>>Stefano.
>
>
> Hold on. In another thread (not sure when/what) we decided that
> there would be no distinction about cocoon committers. They are
> committers for the whole of code and docs and would have access
> to the whole cvs.
>
> Your proposal is going against your earlier valid point that
> we ensure there is no "perception that documents are maintained
> by somebody else".
Wait. What I'm thinking is the chance of being able to use a dummy CVS
user for a potential CMS that uses CVS as its document repository (won't
provide fast xpath queries (well, we could index it side-by-side with
xindice anyway, but will provide metadata and versioning).
The infrastructure teams *does* *not* like service-attached accounts for
icarus/daedalus and this is to prevent the introduction of weaker
security points than SSH to the workflow.
at the same time, we have community oversight over all changes, so even
if somebody routes around security restrictions of our CMS and commits
straight to the CVS bypassing all SSH security (becasue the CMS holds
the private key of that dummy CMS account), he/she will simply write
something on our docs, we'll get a commit email and we'll fix it and
since publishing is manually driven, this won't never end up on the web
site.
this is, IMO, a very safe architecture even if our CMS is exploited and
its security bypassed.
but if we allow the CMS to work on the *entire* CVS repository (thus
being able to touch code), I can predict that infrastructure will feel
much more uneasy.
So, the proposal is not about forcing docu-oriented people as
second-class citizens, but potentially allowing people (or services)
that *request* or *need* to be docu-oriented-only to be able to be given
karma like that.
Stefano.
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS
module
Posted by David Crossley <cr...@indexgeo.com.au>.
Stefano Mazzocchi wrote:
> Pier Fumagalli wrote:
<snip/>
> >
> > Folks, do you know that there's the possibility to alias certain subparts of
> > a particular CVS repository from another repository?
> >
> > Like "cocoon-2.1/src/docs" can be stored in the "cocoon-docs" repository.
> >
> > Apache does it already with its httpd-docs repository, aliased to
> > httpd-2.0/docs (or something like it)...
>
> Uh, that sounds *AWESOME*!
>
> Could it be possible, then, to restrict access of some committers only
> to the doc module but have commits coming thru the *main* module land in
> there as well?
>
> That would solve all issues at once, I guess.
>
> Stefano.
Hold on. In another thread (not sure when/what) we decided that
there would be no distinction about cocoon committers. They are
committers for the whole of code and docs and would have access
to the whole cvs.
Your proposal is going against your earlier valid point that
we ensure there is no "perception that documents are maintained
by somebody else".
--David
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS
module
Posted by Pier Fumagalli <pi...@betaversion.org>.
On 25/3/03 9:14 am, "Stefano Mazzocchi" <st...@apache.org> wrote:
> Pier Fumagalli wrote:
>>
>> Folks, do you know that there's the possibility to alias certain subparts of
>> a particular CVS repository from another repository?
>>
>> Like "cocoon-2.1/src/docs" can be stored in the "cocoon-docs" repository.
>>
>> Apache does it already with its httpd-docs repository, aliased to
>> httpd-2.0/docs (or something like it)...
>
> Uh, that sounds *AWESOME*!
>
> Could it be possible, then, to restrict access of some committers only
> to the doc module but have commits coming thru the *main* module land in
> there as well?
In theory yes... We can play around with Karma for directories as well...
> That would solve all issues at once, I guess.
If you say so! :-) I'm going to try it out on my repo at work, and will tell
you what/how can be done exactly...
Pier
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Stefano Mazzocchi <st...@apache.org>.
Pier Fumagalli wrote:
> On 24/3/03 9:13 am, "Jeff Turner" <je...@apache.org> wrote:
>
>
>>On Mon, Mar 24, 2003 at 07:31:39AM +0100, Steven Noels wrote:
>>
>>>In order to get one little step closer to the 'new' document
>>>infrastructure, many of us seek clarity whether we should move docs to a
>>>separate CVS module or not. The benefits and downfalls are largely
>>>known, so let's vote on this and get this issue cleared.
>>>
>>>My own personal bias: don't forget the different Cocoon _versions_ are
>>>now stored in separate modules, too.
>>>
>>>Please cast your vote:
>>>
>>
>>[ ] creation of cocoon-docs module
>>[+1] docs should stay in src/documentation of the code tree module(s)
>>
>>Because:
>>
>>- With a separate cocoon-docs module, I don't see how the various
>>code-related files (status.xml, jars.xml) are obtained.
>>
>>- Making a separate doc module kills outright any future efforts to
>>generate docs directly from code (e.g. a component manual).
>>
>>- I think that by default, doc changes should only apply to one codebase
>>(2.0 or 2.1). There are many differences that are *meant* to be there,
>>that could get lost if 2.0 and 2.1 docs are generated from a common
>>source.
>
>
> Folks, do you know that there's the possibility to alias certain subparts of
> a particular CVS repository from another repository?
>
> Like "cocoon-2.1/src/docs" can be stored in the "cocoon-docs" repository.
>
> Apache does it already with its httpd-docs repository, aliased to
> httpd-2.0/docs (or something like it)...
Uh, that sounds *AWESOME*!
Could it be possible, then, to restrict access of some committers only
to the doc module but have commits coming thru the *main* module land in
there as well?
That would solve all issues at once, I guess.
Stefano.
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS
module
Posted by Andrew Savory <an...@luminas.co.uk>.
On Mon, 24 Mar 2003, Pier Fumagalli wrote:
> Folks, do you know that there's the possibility to alias certain subparts of
> a particular CVS repository from another repository?
>
> Like "cocoon-2.1/src/docs" can be stored in the "cocoon-docs" repository.
>
> Apache does it already with its httpd-docs repository, aliased to
> httpd-2.0/docs (or something like it)...
This still leaves us with the problem of the docs being kept within one
codebase (eg 2.1) though, which would be wrong if we're updating them for
a 2.2 repository.
Useful to know, though ...
Andrew.
--
Andrew Savory Email: andrew@luminas.co.uk
Managing Director Tel: +44 (0)870 741 6658
Luminas Internet Applications Fax: +44 (0)700 598 1135
This is not an official statement or order. Web: www.luminas.co.uk
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS
module
Posted by Pier Fumagalli <pi...@betaversion.org>.
On 24/3/03 9:13 am, "Jeff Turner" <je...@apache.org> wrote:
> On Mon, Mar 24, 2003 at 07:31:39AM +0100, Steven Noels wrote:
>> In order to get one little step closer to the 'new' document
>> infrastructure, many of us seek clarity whether we should move docs to a
>> separate CVS module or not. The benefits and downfalls are largely
>> known, so let's vote on this and get this issue cleared.
>>
>> My own personal bias: don't forget the different Cocoon _versions_ are
>> now stored in separate modules, too.
>>
>> Please cast your vote:
>>
> [ ] creation of cocoon-docs module
> [+1] docs should stay in src/documentation of the code tree module(s)
>
> Because:
>
> - With a separate cocoon-docs module, I don't see how the various
> code-related files (status.xml, jars.xml) are obtained.
>
> - Making a separate doc module kills outright any future efforts to
> generate docs directly from code (e.g. a component manual).
>
> - I think that by default, doc changes should only apply to one codebase
> (2.0 or 2.1). There are many differences that are *meant* to be there,
> that could get lost if 2.0 and 2.1 docs are generated from a common
> source.
Folks, do you know that there's the possibility to alias certain subparts of
a particular CVS repository from another repository?
Like "cocoon-2.1/src/docs" can be stored in the "cocoon-docs" repository.
Apache does it already with its httpd-docs repository, aliased to
httpd-2.0/docs (or something like it)...
Pier
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
Posted by Stefano Mazzocchi <st...@apache.org>.
Andrew Savory wrote:
> On Mon, 24 Mar 2003, Stefano Mazzocchi wrote:
>
>>I want a serious CMS, damn it! with a dead-simple (not xopus!) inline
>>editor on top! and using CVS as a repository! and transforming
>>structured text in xdocs with perfect roundtripping!
>
> +1 from me! I do think having a cocoon-docs CVS would help rather than
> hinder this though, as we could easily allow updating of the documentation
> with no danger that any of the code might be attacked by an errant CMS.
Yes, I was thinking exactly this when I changed my vote, even if I don't
think that the apache infrastructure will ever allow a CMS to become
*committer* to the CVS repository.
however, separating documents from code in different modules, would
allow (in theory, at least) to setup a CMS that has commit priviledges
only on the documentation module, thus leaving the code fully protected
from potential exploits of the CMS.
If there is *one* single change of having such CMS cleared by our
infrastructure team, separating the modules will sure increase this
chance, not reduce it.
This is, IMO, the biggest argument in favor of such a separation.
Stefano.
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
Posted by Andrew Savory <an...@luminas.co.uk>.
Hi,
Just to add my thoughts to this. Regarding transition to 2.1 making 2.0
docs obsolete - this is a fair comment, but what do we do when we start
working on 2.2?
I do appreciate Stefano's comments about blocks though, and how code and
documentation in that instance belong together, and to be honest, this
wasn't something I'd thought about. I don't see any easy answer to that
other than that the documentation that goes with the blocks should be
javadoc-style only, and reference/howto material belongs in the main docs
tree. It would be annoying to have to grab block X just to get the
documentation for it, when following links in the documentation you do
have.
On Mon, 24 Mar 2003, Stefano Mazzocchi wrote:
> I want a serious CMS, damn it! with a dead-simple (not xopus!) inline
> editor on top! and using CVS as a repository! and transforming
> structured text in xdocs with perfect roundtripping!
+1 from me! I do think having a cocoon-docs CVS would help rather than
hinder this though, as we could easily allow updating of the documentation
with no danger that any of the code might be attacked by an errant CMS.
Andrew.
--
Andrew Savory Email: andrew@luminas.co.uk
Managing Director Tel: +44 (0)870 741 6658
Luminas Internet Applications Fax: +44 (0)700 598 1135
This is not an official statement or order. Web: www.luminas.co.uk
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
Posted by Stefano Mazzocchi <st...@apache.org>.
Diana Shannon wrote:
>
> On Monday, March 24, 2003, at 10:34 AM, Steven Noels wrote:
>
>>
>>>> My own belly tells me that people will write more and better user
>>>> documentation if they get some proper playground. Having to worry
>>>> about code sitting right beside their documents will not bring peace
>>>> in their minds.
>>>
>>> Ok, please, explain to me why the cocoon CVS module is not a proper
>>> playground for people writing docs because I don't understand.
>
>
> A few Belly Thoughts:
>
> + Consider what we are about to implement in 2.1. Forrest generates our
> web site and docs, based on the contents of xdocs. What if docs people
> want to experiment? How can we do that if the place where docs live,
> next to code, it automatically considered final by our publishing
> mechanism. Therefore, all experiments either break the automatic
> publishing or get published to the web (which we may not want).
>
> + What about prototyping new doc approaches, like reference pages for
> logicsheets, as Andrew recently proposed. What if we need some special
> jar for that, something totally related to docs, not the cvs. Where
> shall we put it? Bloat the code repo for docs-only needs? Put it in
> Forrest? Well, what if it's outside the "concern" of Forrest or we don't
> want to wait for Forrest -- e.g. experiment a little internally?
>
> + CMS issues, already raised in previous posts.
>
> + What if we start some global docs transition, say based on adding
> Dublin Core data, etc. What if we have only a partial set of docs
> changed over. Wouldn't a docs module, with an experimental/head branch,
> be a great place for this collaboration?
All right.
I'm changing my vote from -1 to +1. I trust the people wanting this
enough to appreciate the fact that they might point out that I'm wrong
and I'm not seeing where the problems are.
I hope that others reconsider their vote.
Stefano.
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Diana Shannon <sh...@apache.org>.
On Monday, March 24, 2003, at 10:34 AM, Steven Noels wrote:
>
>>> My own belly tells me that people will write more and better user
>>> documentation if they get some proper playground. Having to worry
>>> about code sitting right beside their documents will not bring peace
>>> in their minds.
>> Ok, please, explain to me why the cocoon CVS module is not a proper
>> playground for people writing docs because I don't understand.
A few Belly Thoughts:
+ Consider what we are about to implement in 2.1. Forrest generates our
web site and docs, based on the contents of xdocs. What if docs people
want to experiment? How can we do that if the place where docs live,
next to code, it automatically considered final by our publishing
mechanism. Therefore, all experiments either break the automatic
publishing or get published to the web (which we may not want).
+ What about prototyping new doc approaches, like reference pages for
logicsheets, as Andrew recently proposed. What if we need some special
jar for that, something totally related to docs, not the cvs. Where
shall we put it? Bloat the code repo for docs-only needs? Put it in
Forrest? Well, what if it's outside the "concern" of Forrest or we don't
want to wait for Forrest -- e.g. experiment a little internally?
+ CMS issues, already raised in previous posts.
+ What if we start some global docs transition, say based on adding
Dublin Core data, etc. What if we have only a partial set of docs
changed over. Wouldn't a docs module, with an experimental/head branch,
be a great place for this collaboration?
Diana
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
Posted by Steven Noels <st...@outerthought.org>.
On 24/03/2003 16:09 Stefano Mazzocchi wrote:
(About pointy tags: send over your p-Book and I'll install XXE for you.
XXE reminds me of why I am so reluctant to believe browser-based widgets
will never be able to edit anything else but semantically poor
(X)HTML-like fragments)
>> My own belly tells me that people will write more and better user
>> documentation if they get some proper playground. Having to worry
>> about code sitting right beside their documents will not bring peace
>> in their minds.
>
>
> Ok, please, explain to me why the cocoon CVS module is not a proper
> playground for people writing docs because I don't understand.
1) up to lately, the docs target has been failing on quite some occasions.
2) up to lately, the 'requirement' (?) to sync branches brought even
more relunctancy.
3) there's too much documentation already (!): people prefer a
clean-sheet approach (look at the Wiki, and don't think all of it is
'draft' or 'playground') - particularly on the entry level
documentation/trails
4) up to lately, the entire Cocoon CVS module was needed to work on
documentation. Now, people could possibly check-out only
src/documentation and work on that using a binary install of Forrest.
5) (minor) some of the docs can hardly be concerned authorative
(http://xml.apache.org/cocoon/tutorial/index.html) and should not be in
Cocoon CVS
All in all, most of my playground them has to do with it 'being vacant',
rather than technics or tools.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [rant] Re: [vote] micro-decision for docs: creation of
cocoon-docs CVS module
Posted by Pier Fumagalli <pi...@betaversion.org>.
On 25/3/03 9:23 am, "Stefano Mazzocchi" <st...@apache.org> wrote:
> Pier Fumagalli wrote:
>> On 24/3/03 3:09 pm, "Stefano Mazzocchi" <st...@apache.org> wrote:
>>
>>
>>> Anyway, we can't force people to do anything: if they won't migrate from
>>> 2.0, we have failed and we should start reconsidering our architectural
>>> strategies because our user base is not following us.
>>
>>
>> Hmm.. I don't think you're right on this, Stefano... Look at HTTPd, still a
>> lot of people are using 1.3, when 2.0 is delivering (for example) _A_LOT_
>> more performance than the old tree...
>>
>> Still, a huge part of the user base didn't "switch" just yet...
>
> key words: 'just yet'.
Gotcha...
> I didn't say "how long". AFAIK, many people are still using Cocoon 1.8.2
> in production and it's been running for two years without failing once.
>
> Yet, everybody considers Cocoon 1.x dead and no development is taking
> place anymore and nobody objects it.
>
> Cocoon 2.0.x will remain there potentially for years and will be used
> for many more in production environments.
Like us at VNU, where we still are running a couple of httpd 1.2.6 :-)
> Still, if development doesn't move on and transition isn't smooth, we
> are actually forking the project.
>
> If development on HTTPD continues on both fronts, they failed since the
> community shows that 2.0 is nothing better than what they already had.
>
> i don't think this is the case, I think it's just a matter of time.
>
> As it will be for Cocoon 2.1.
I'd say: as it is _already_ for Cocoon 2.0/2.1... Since we split the repos
(and if I'm not wrong), we had 32 commits to the 2.0 repo, more than 370 to
the 2.1 one... So... We're all happy campers! :-)
Pier
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
Posted by Stefano Mazzocchi <st...@apache.org>.
Pier Fumagalli wrote:
> On 24/3/03 3:09 pm, "Stefano Mazzocchi" <st...@apache.org> wrote:
>
>
>>Anyway, we can't force people to do anything: if they won't migrate from
>>2.0, we have failed and we should start reconsidering our architectural
>>strategies because our user base is not following us.
>
>
> Hmm.. I don't think you're right on this, Stefano... Look at HTTPd, still a
> lot of people are using 1.3, when 2.0 is delivering (for example) _A_LOT_
> more performance than the old tree...
>
> Still, a huge part of the user base didn't "switch" just yet...
key words: 'just yet'.
I didn't say "how long". AFAIK, many people are still using Cocoon 1.8.2
in production and it's been running for two years without failing once.
Yet, everybody considers Cocoon 1.x dead and no development is taking
place anymore and nobody objects it.
Cocoon 2.0.x will remain there potentially for years and will be used
for many more in production environments.
Still, if development doesn't move on and transition isn't smooth, we
are actually forking the project.
If development on HTTPD continues on both fronts, they failed since the
community shows that 2.0 is nothing better than what they already had.
i don't think this is the case, I think it's just a matter of time.
As it will be for Cocoon 2.1.
if a project creates a new generation and their development base splits,
they are, in fact, forking the project.
See Tomcat.
This is the *worst* thing that can happen to an open source project.
Luckily, Apache is very tollerant at forced cohabitation and eventually,
split development bases remerge down the road.
Stefano.
Re: [rant] Re: [vote] micro-decision for docs: creation ofcocoon-docs CVS module
Posted by "J.D. Daniels" <jd...@datatrio.com>.
Actually... I dont httpd is a fiar example. There is a reason for that...
there is not many modules that function correctly under 2.0... we are only
waiting for them to catch up :D at my last count, there are 4 that i use
that dont work. (Among them mod_jk)
By itself, 2.0 kicks butt... but i can't use it in production yet :(
JD
----- Original Message -----
From: "Pier Fumagalli" <pi...@betaversion.org>
To: <co...@xml.apache.org>
Sent: Monday, March 24, 2003 12:04 PM
Subject: Re: [rant] Re: [vote] micro-decision for docs: creation
ofcocoon-docs CVS module
> On 24/3/03 3:09 pm, "Stefano Mazzocchi" <st...@apache.org> wrote:
>
> > Anyway, we can't force people to do anything: if they won't migrate from
> > 2.0, we have failed and we should start reconsidering our architectural
> > strategies because our user base is not following us.
>
> Hmm.. I don't think you're right on this, Stefano... Look at HTTPd, still
a
> lot of people are using 1.3, when 2.0 is delivering (for example) _A_LOT_
> more performance than the old tree...
>
> Still, a huge part of the user base didn't "switch" just yet...
>
> Pier
>
Re: [rant] Re: [vote] micro-decision for docs: creation of
cocoon-docs CVS module
Posted by Pier Fumagalli <pi...@betaversion.org>.
On 24/3/03 3:09 pm, "Stefano Mazzocchi" <st...@apache.org> wrote:
> Anyway, we can't force people to do anything: if they won't migrate from
> 2.0, we have failed and we should start reconsidering our architectural
> strategies because our user base is not following us.
Hmm.. I don't think you're right on this, Stefano... Look at HTTPd, still a
lot of people are using 1.3, when 2.0 is delivering (for example) _A_LOT_
more performance than the old tree...
Still, a huge part of the user base didn't "switch" just yet...
Pier
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
Posted by Stefano Mazzocchi <st...@apache.org>.
Steven Noels wrote:
> On 24/03/2003 14:23 Stefano Mazzocchi wrote:
>
>> I don't expect 2.0 to live long after 2.1 is out. There is no reason to.
>
>
> To be really honest, I'd like to see some facts backing this statement.
> Not technical facts, but truly compelling reasons to make the switch. If
> people don't go with the flow, or with xmlform, why should there be a
> reason to switch?
Tons of it:
1) modularity: you can include in your cocoon, only what you really
need, keeping memory lower and lowering the chance of bugs and potential
security holes
2) interpreted sitemap: reduces your try fail cycle
3) tunable pipelines: you can have caching/non-caching granularity
4) better proxy friendlyness: improves your speed for static resources.
These are the most evident but there are tons of them if you look at
changes.xml.
Anyway, we can't force people to do anything: if they won't migrate from
2.0, we have failed and we should start reconsidering our architectural
strategies because our user base is not following us.
Still, given the feedback i received on 2.1, I don't think this will
happen, as it didn't happen between cocoon 1.x and 2.x even if the
changes were so radical.
The 2.0 -> 2.1 transition will be piece of cake compared to that, trust me.
>> If there is something back-incompatible, it's a bug and it will be
>> fixed. Nobody should have problems in switching to 2.1 and if they
>> did, we fix their problems because we (and them) *expect* an easy
>> migration.
>>
>> At that point, there will be only *one* repository for docs and it
>> will live close to the code it belongs to.
>
>
> Sigh. I don't understand, and perhaps will never understand, what this
> obsession is with keeping docs close to code.
There is no 'obsession', Steven. I'm wide open to arguments that tell me
why keeping the docs with the code is wrong.
Diana's arguments about duplication of effort are good ones, but I
pointed out that they are only short-term ones until the transition is
finished and should not influence our longer-term vision.
> I see three types of documentation involved in a generic software project:
>
> * code-based documentation, aka Javadocs & comments
> * reference documentation, which could possibly be partly generated out
> of the above, and states the exact input/output requirements and
> behavior of components
Javadocs has one huge drawback: they aren't semantic. If we had semantic
javadocs, we could integrate more meaningful javadocs into our own
documentation and this would be *so* nicer than what we have today.
javadocs are cool and useful, but they are too developer oriented.
Still, if we had semantic capabilities, we could write skins to make it
more 'forrest-friendly' for example, and provide more coherent visual
semantics. Worth thinking for forrest, IMO.
> * 'user' documentation, like 'building new Cocoon components', or
> 'installing Cocoon on Znorbaf appserver'
I agree the first two are somewhat different from the last one.
> I agree blocks & modular builds kinda spoil my picture, but the reason
> why I think all of these are wildly different, has to do with flow and
> access trails. Ultimately, one might think docs will be generated using
> some Javadoc++ process, as some novel language features in c# and Java,
> and tools like xdoclet are trying to suggest. I'm still one of these
> firm (silly?) believers that good user documentation is created with a
> blank editor screen in front of you, and that a decently written
> document of several screens long might be more helpful than the
> technically correct, hyperlinked-to-the-max, autogenerated alternative.
Oh, I can't agree more. Believe me.
> For some examples, please see:
>
> - http://xml.apache.org/forrest/your-project.html
> - http://xml.apache.org/forrest/linking.html
> - http://wiki.cocoondev.org/Wiki.jsp?page=DevelopingComponents
> - http://httpd.apache.org/docs-2.0/mod/mod_include.html
> -
> http://www.zope.org/Documentation/Books/ZopeBook/current/SimpleExamples.stx
>
> Nicola might be right in me being wrong, i.e. that I'm focusing too much
> on the Cocoon website. If that is the case, I'm sorry, my view must be
> warped then.
>
>> In the future, i would like block-specific documentation to remain
>> inside the blocks. Everything should remain as close as possible to
>> the code: javadocs, tests, metadata in general even documentation,
>> configurations, avalon roles, block metainfo and what not.
>>
>> creating a single docu repository is, IMO, a very dangerous road because:
>>
>> 1) it gives a perception that documents are maintained by somebody
>> else. This perception is already here and it's probably my fault and
>> this is causing pain and trouble to many people. I want this to be
>> fixed in order for the process to be more scalable.
>
>
> I don't see the point in addressing a perception which surely isn't
> generalized. Some people like to work on docs, and they will, and the
> entrance barrier should be 'low enough' for them. Some people believe
> plenty of Javadoc will do the job, alas to be read only by co-developers
> IMHO. But we can't force anyone of them to become the other - we should
> support both styles.
I agree.
> Making Cocoon user documentation independent of Cocoon itself might be a
> good first step, that's why the Forrest transitioning is really, really
> good.
yes
> I agree I said something like 'we the doco people'. What I meant was the
> 'people usually contributing to documentation'. Some of them are
> developers, some of them not.
I haven't contributed to documentation because I love xml but I bloody
hate writing it and I love writing structured text but I hate the fact
that wikis are so damn idiotic to navigate.
I want a serious CMS, damn it! with a dead-simple (not xopus!) inline
editor on top! and using CVS as a repository! and transforming
structured text in xdocs with perfect roundtripping!
And there's exactly where I want to push to go.
> My own belly tells me that people will write more and better user
> documentation if they get some proper playground. Having to worry about
> code sitting right beside their documents will not bring peace in their
> minds.
Ok, please, explain to me why the cocoon CVS module is not a proper
playground for people writing docs because I don't understand.
Stefano.
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Diana Shannon <sh...@apache.org>.
On Monday, March 24, 2003, at 09:15 AM, Steven Noels wrote:
> On 24/03/2003 14:23 Stefano Mazzocchi wrote:
>
>> I don't expect 2.0 to live long after 2.1 is out. There is no reason
>> to.
>
> To be really honest, I'd like to see some facts backing this statement.
> Not technical facts, but truly compelling reasons to make the switch.
> If people don't go with the flow, or with xmlform, why should there be
> a reason to switch?
Furthermore, there will be differences between 2.1 and 2.2 that
inevitably emerge ... I personally think transition periods between
software versions are the rule, not the exception. Docs which can point
out the differences are helpful, especially to new users. It would be so
easy with a single set of docs. I've worked with Cocoon since 1.7. In my
experience, we've always been transitioning. I think it's particularly
hard it is for users to get up to speed with such differences. Our
changes doc is overly terse for new users.
>
>> If there is something back-incompatible, it's a bug and it will be
>> fixed. Nobody should have problems in switching to 2.1 and if they
>> did, we fix their problems because we (and them) *expect* an easy
>> migration.
>> At that point, there will be only *one* repository for docs and it
>> will live close to the code it belongs to.
>
> Sigh. I don't understand, and perhaps will never understand, what this
> obsession is with keeping docs close to code.
In some ways, you could argue the "genie is already out of the bottle."
Look at CocoonWiki (where docs are "far away" from code). Does anyone
realize there are 44 How-Tos there? Now compare that to our cvs count:
12 (with only half being technical, e.g. not
administrative/editorial-oriented). Interesting.
<snip what="doc types" why="agree with Steven" />
>> In the future, i would like block-specific documentation to remain
>> inside the blocks. Everything should remain as close as possible to
>> the code: javadocs, tests, metadata in general even documentation,
>> configurations, avalon roles, block metainfo and what not.
>> creating a single docu repository is, IMO, a very dangerous road
>> because:
>> 1) it gives a perception that documents are maintained by somebody
>> else. This perception is already here and it's probably my fault and
>> this is causing pain and trouble to many people. I want this to be
>> fixed in order for the process to be more scalable.
But in some ways **many** docs are already being maintained by "somebody
else" -- our users on wiki. Where documents "live" in some ways should
be secondary to how to provide the best access to those who want to
improve them. However, I still can't see a future CMS which reads/writes
a majority of its doc content from a code repository. It simply makes no
sense to me, from a SoC point of view. Some may argue, well we don't
have a CMS yet, but a "poor man's" CMS seems very doable now, given the
excellent work already available from many on this very list.
>> 2) it has a short-term impact on a short-term problem that is an
>> evidence of a much bigger problem: our inability to do faster
>> releases. we should design the entire system to allow us to make
>> faster releases and this should be our goal, even if potentially
>> disruptive for the short term.
>
> I don't see the point in addressing a perception which surely isn't
> generalized. Some people like to work on docs, and they will, and the
> entrance barrier should be 'low enough' for them. Some people believe
> plenty of Javadoc will do the job, alas to be read only by
> co-developers IMHO. But we can't force anyone of them to become the
> other - we should support both styles.
>
> Making Cocoon user documentation independent of Cocoon itself might be
> a good first step, that's why the Forrest transitioning is really,
> really good.
>
> I agree I said something like 'we the doco people'. What I meant was
> the 'people usually contributing to documentation'. Some of them are
> developers, some of them not.
>
> My own belly tells me that people will write more and better user
> documentation if they get some proper playground. Having to worry about
> code sitting right beside their documents will not bring peace in their
> minds.
+1 Well stated.
Diana
[rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
Posted by Steven Noels <st...@outerthought.org>.
On 24/03/2003 14:23 Stefano Mazzocchi wrote:
> I don't expect 2.0 to live long after 2.1 is out. There is no reason to.
To be really honest, I'd like to see some facts backing this statement.
Not technical facts, but truly compelling reasons to make the switch. If
people don't go with the flow, or with xmlform, why should there be a
reason to switch?
> If there is something back-incompatible, it's a bug and it will be
> fixed. Nobody should have problems in switching to 2.1 and if they did,
> we fix their problems because we (and them) *expect* an easy migration.
>
> At that point, there will be only *one* repository for docs and it will
> live close to the code it belongs to.
Sigh. I don't understand, and perhaps will never understand, what this
obsession is with keeping docs close to code.
I see three types of documentation involved in a generic software project:
* code-based documentation, aka Javadocs & comments
* reference documentation, which could possibly be partly generated
out of the above, and states the exact input/output requirements and
behavior of components
* 'user' documentation, like 'building new Cocoon components', or
'installing Cocoon on Znorbaf appserver'
I agree blocks & modular builds kinda spoil my picture, but the reason
why I think all of these are wildly different, has to do with flow and
access trails. Ultimately, one might think docs will be generated using
some Javadoc++ process, as some novel language features in c# and Java,
and tools like xdoclet are trying to suggest. I'm still one of these
firm (silly?) believers that good user documentation is created with a
blank editor screen in front of you, and that a decently written
document of several screens long might be more helpful than the
technically correct, hyperlinked-to-the-max, autogenerated alternative.
For some examples, please see:
- http://xml.apache.org/forrest/your-project.html
- http://xml.apache.org/forrest/linking.html
- http://wiki.cocoondev.org/Wiki.jsp?page=DevelopingComponents
- http://httpd.apache.org/docs-2.0/mod/mod_include.html
-
http://www.zope.org/Documentation/Books/ZopeBook/current/SimpleExamples.stx
Nicola might be right in me being wrong, i.e. that I'm focusing too much
on the Cocoon website. If that is the case, I'm sorry, my view must be
warped then.
> In the future, i would like block-specific documentation to remain
> inside the blocks. Everything should remain as close as possible to the
> code: javadocs, tests, metadata in general even documentation,
> configurations, avalon roles, block metainfo and what not.
>
> creating a single docu repository is, IMO, a very dangerous road because:
>
> 1) it gives a perception that documents are maintained by somebody else.
> This perception is already here and it's probably my fault and this is
> causing pain and trouble to many people. I want this to be fixed in
> order for the process to be more scalable.
I don't see the point in addressing a perception which surely isn't
generalized. Some people like to work on docs, and they will, and the
entrance barrier should be 'low enough' for them. Some people believe
plenty of Javadoc will do the job, alas to be read only by co-developers
IMHO. But we can't force anyone of them to become the other - we should
support both styles.
Making Cocoon user documentation independent of Cocoon itself might be a
good first step, that's why the Forrest transitioning is really, really
good.
I agree I said something like 'we the doco people'. What I meant was the
'people usually contributing to documentation'. Some of them are
developers, some of them not.
My own belly tells me that people will write more and better user
documentation if they get some proper playground. Having to worry about
code sitting right beside their documents will not bring peace in their
minds.
This all IMHO.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Stefano Mazzocchi <st...@apache.org>.
Diana Shannon wrote:
> [ +1 ] creation of cocoon-docs module
> [ ] docs should stay in src/documentation of the code tree module(s)
>
> I feel strongly about this, give the past year of my watching cvs
> commits. The fact remains that many committers don't update both doc
> branches when committing docs. If someone needs **facts** check out the
> cvs thread when we were all updating the cvs committer list as
> active/inactive/emeritus/etc. It's quite revealing to see who updated
> release branch and who did not. It's also a fact that a vast majority of
> our docs are identical in cocoon 2.0 and 2.1 branches. The idea of a
> single docs module is supposed to make it easier and more obvious for
> committers when committing doc patches.
Ok.
> So, if this fails, we need some kind of discussion how to encourage
> people to be more thoughtful when committing. I'm not going to spend the
> next year of my commiter life syncing docs in code repos.
I hear you, Diana. I hear you.
> I also want to respond to some of Jeff's concerns below.
>
> On Monday, March 24, 2003, at 04:13 AM, Jeff Turner wrote:
>
>>>
>>> Please cast your vote:
>>>
>> [ ] creation of cocoon-docs module
>> [+1] docs should stay in src/documentation of the code tree module(s)
>>
>> Because:
>>
>> - With a separate cocoon-docs module, I don't see how the various
>> code-related files (status.xml, jars.xml) are obtained.
>
>
> Locally, referenced via a path set in a configuration file. If code
> repos aren't available/downloaded, info can also be looked up online via
> a parsed view-cvs data. Still, I don't think it's too much to expect
> from committers, to have all three repos.
This is true.
>> - Making a separate doc module kills outright any future efforts to
>> generate docs directly from code (e.g. a component manual).
>
>
> Not at all. There's no reason a doc-generating mechanism can't look up
> or gather info/files from other cvs code repos during a docs build.
This will reduce the ability for people to generate documents from being
offline, but since we will include a prebuilt documentation in our
distribution, this doesn't really matter since users won't be making doc
changes anyway.
As for committers, it's not too much to expect them to have downloaded
all modules.
>> - I think that by default, doc changes should only apply to one codebase
>> (2.0 or 2.1). There are many differences that are *meant* to be there,
>> that could get lost if 2.0 and 2.1 docs are generated from a common
>> source.
>
>
> Not true in our current case. Of course, this may evolve to be the case
> down the road, but as I said above, most docs at the present time are
> identical (exceptions: install, catalog, some how-tos, some webapp pages).
I think this is the main point and I would like to give some thoughts.
I don't expect 2.0 to live long after 2.1 is out. There is no reason to.
If there is something back-incompatible, it's a bug and it will be
fixed. Nobody should have problems in switching to 2.1 and if they did,
we fix their problems because we (and them) *expect* an easy migration.
At that point, there will be only *one* repository for docs and it will
live close to the code it belongs to.
In the future, i would like block-specific documentation to remain
inside the blocks. Everything should remain as close as possible to the
code: javadocs, tests, metadata in general even documentation,
configurations, avalon roles, block metainfo and what not.
creating a single docu repository is, IMO, a very dangerous road because:
1) it gives a perception that documents are maintained by somebody else.
This perception is already here and it's probably my fault and this is
causing pain and trouble to many people. I want this to be fixed in
order for the process to be more scalable.
2) it has a short-term impact on a short-term problem that is an
evidence of a much bigger problem: our inability to do faster releases.
we should design the entire system to allow us to make faster releases
and this should be our goal, even if potentially disruptive for the
short term.
So, at the end, since 2.0 is going away, we should plan for 2.1 with
full steam and plan for that, living the transition as a potential
teacher for future need.
Stefano.
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Steven Noels <st...@outerthought.org>.
On 26/03/2003 7:31 David Crossley wrote:
> I presume that the website would then get generated
> from the head cvs rather than from the last release.
> Currently we do it the other way around, which may
> be another reason for "the disconnect".
The website should contain documentation about _released_ versions, and
as such, is lacking in some perspectives. If two released versions are
available 'out there', we can have two versions of the site side-by-side:
cocoon.apache.org
/docs/2.0/
/docs/2.1/
cocoon.apache.org containing version-agnostic information (like whoweare
and some general intro stuff), and docs being confined into a deeper
(and version-specific) part of the URI namespace
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS
module
Posted by David Crossley <cr...@indexgeo.com.au>.
[ ] creation of cocoon-docs module
[+1] docs should stay in src/documentation of the code tree module(s)
Jeff Turner wrote:
<snip/>
> I think the disconnect is around the purpose of the 2.0 branch. I think
> of 2.0.x as a _maintenance_ branch. Just as only bugfixes get into the
> code, so only 'bugfixes' need get into the docs. 2.0 is finished; new
> features (and new documentation) should go in 2.1. If someone wants to
> backport new features and new docs to 2.0, good for them. If they don't,
> that's fine too.
Excellent observation Jeff, thanks. This eases the
pain quite a lot.
I presume that the website would then get generated
from the head cvs rather than from the last release.
Currently we do it the other way around, which may
be another reason for "the disconnect".
--David
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Jeff Turner <je...@apache.org>.
On Mon, Mar 24, 2003 at 07:50:36AM -0500, Diana Shannon wrote:
> [ +1 ] creation of cocoon-docs module
> [ ] docs should stay in src/documentation of the code tree module(s)
>
> I feel strongly about this, give the past year of my watching cvs
> commits. The fact remains that many committers don't update both doc
> branches when committing docs. If someone needs **facts** check out the
> cvs thread when we were all updating the cvs committer list as
> active/inactive/emeritus/etc. It's quite revealing to see who updated
> release branch and who did not. It's also a fact that a vast majority of
> our docs are identical in cocoon 2.0 and 2.1 branches. The idea of a
> single docs module is supposed to make it easier and more obvious for
> committers when committing doc patches.
I think the disconnect is around the purpose of the 2.0 branch. I think
of 2.0.x as a _maintenance_ branch. Just as only bugfixes get into the
code, so only 'bugfixes' need get into the docs. 2.0 is finished; new
features (and new documentation) should go in 2.1. If someone wants to
backport new features and new docs to 2.0, good for them. If they don't,
that's fine too.
> So, if this fails, we need some kind of discussion how to encourage
> people to be more thoughtful when committing. I'm not going to spend the
> next year of my commiter life syncing docs in code repos.
Now you see what kind of twisty thinking justifies not synching with 2.0
8-)
> I also want to respond to some of Jeff's concerns below.
Having cocoon-docs rely on cocoon-2.1 seems quite reasonable.
--Jeff
...
> Diana
>
RE: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by John Morrison <jo...@ntlworld.com>.
> From: Diana Shannon [mailto:shannon@apache.org]
>
> Locally, referenced via a path set in a configuration file. If code
> repos aren't available/downloaded, info can also be looked up online via
> a parsed view-cvs data. Still, I don't think it's too much to expect
> from committers, to have all three repos.
Would it be better to cvs co the document repository inside the
cocoon one? That way documentation only folk don't need everything
and code only developers don't have to co docs (not that they shouldn't
anyway!).
J.
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Diana Shannon <sh...@apache.org>.
[ +1 ] creation of cocoon-docs module
[ ] docs should stay in src/documentation of the code tree module(s)
I feel strongly about this, give the past year of my watching cvs
commits. The fact remains that many committers don't update both doc
branches when committing docs. If someone needs **facts** check out the
cvs thread when we were all updating the cvs committer list as
active/inactive/emeritus/etc. It's quite revealing to see who updated
release branch and who did not. It's also a fact that a vast majority of
our docs are identical in cocoon 2.0 and 2.1 branches. The idea of a
single docs module is supposed to make it easier and more obvious for
committers when committing doc patches.
So, if this fails, we need some kind of discussion how to encourage
people to be more thoughtful when committing. I'm not going to spend the
next year of my commiter life syncing docs in code repos.
I also want to respond to some of Jeff's concerns below.
On Monday, March 24, 2003, at 04:13 AM, Jeff Turner wrote:
>>
>> Please cast your vote:
>>
> [ ] creation of cocoon-docs module
> [+1] docs should stay in src/documentation of the code tree module(s)
>
> Because:
>
> - With a separate cocoon-docs module, I don't see how the various
> code-related files (status.xml, jars.xml) are obtained.
Locally, referenced via a path set in a configuration file. If code
repos aren't available/downloaded, info can also be looked up online via
a parsed view-cvs data. Still, I don't think it's too much to expect
from committers, to have all three repos.
> - Making a separate doc module kills outright any future efforts to
> generate docs directly from code (e.g. a component manual).
Not at all. There's no reason a doc-generating mechanism can't look up
or gather info/files from other cvs code repos during a docs build.
> - I think that by default, doc changes should only apply to one codebase
> (2.0 or 2.1). There are many differences that are *meant* to be
> there,
> that could get lost if 2.0 and 2.1 docs are generated from a common
> source.
Not true in our current case. Of course, this may evolve to be the case
down the road, but as I said above, most docs at the present time are
identical (exceptions: install, catalog, some how-tos, some webapp
pages).
Diana
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Diana Shannon <sh...@apache.org>.
[ +1 ] creation of cocoon-docs module
[ ] docs should stay in src/documentation of the code tree module(s)
I feel strongly about this, give the past year of my watching cvs
commits. The fact remains that many committers don't update both doc
branches when committing docs. If someone needs **facts** check out the
cvs thread when we were all updating the cvs committer list as
active/inactive/emeritus/etc. It's quite revealing to see who updated
release branch and who did not. It's also a fact that a vast majority of
our docs are identical in cocoon 2.0 and 2.1 branches. The idea of a
single docs module is supposed to make it easier and more obvious for
committers when committing doc patches.
So, if this fails, we need some kind of discussion how to encourage
people to be more thoughtful when committing. I'm not going to spend the
next year of my commiter life syncing docs in code repos.
I also want to respond to some of Jeff's concerns below.
On Monday, March 24, 2003, at 04:13 AM, Jeff Turner wrote:
>>
>> Please cast your vote:
>>
> [ ] creation of cocoon-docs module
> [+1] docs should stay in src/documentation of the code tree module(s)
>
> Because:
>
> - With a separate cocoon-docs module, I don't see how the various
> code-related files (status.xml, jars.xml) are obtained.
Locally, referenced via a path set in a configuration file. If code
repos aren't available/downloaded, info can also be looked up online via
a parsed view-cvs data. Still, I don't think it's too much to expect
from committers, to have all three repos.
> - Making a separate doc module kills outright any future efforts to
> generate docs directly from code (e.g. a component manual).
Not at all. There's no reason a doc-generating mechanism can't look up
or gather info/files from other cvs code repos during a docs build.
> - I think that by default, doc changes should only apply to one codebase
> (2.0 or 2.1). There are many differences that are *meant* to be
> there,
> that could get lost if 2.0 and 2.1 docs are generated from a common
> source.
Not true in our current case. Of course, this may evolve to be the case
down the road, but as I said above, most docs at the present time are
identical (exceptions: install, catalog, some how-tos, some webapp
pages).
Diana
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS
module
Posted by Pier Fumagalli <pi...@betaversion.org>.
On 24/3/03 9:13 am, "Jeff Turner" <je...@apache.org> wrote:
> On Mon, Mar 24, 2003 at 07:31:39AM +0100, Steven Noels wrote:
>> In order to get one little step closer to the 'new' document
>> infrastructure, many of us seek clarity whether we should move docs to a
>> separate CVS module or not. The benefits and downfalls are largely
>> known, so let's vote on this and get this issue cleared.
>>
>> My own personal bias: don't forget the different Cocoon _versions_ are
>> now stored in separate modules, too.
>>
>> Please cast your vote:
>>
> [ ] creation of cocoon-docs module
> [+1] docs should stay in src/documentation of the code tree module(s)
>
> Because:
>
> - With a separate cocoon-docs module, I don't see how the various
> code-related files (status.xml, jars.xml) are obtained.
>
> - Making a separate doc module kills outright any future efforts to
> generate docs directly from code (e.g. a component manual).
>
> - I think that by default, doc changes should only apply to one codebase
> (2.0 or 2.1). There are many differences that are *meant* to be there,
> that could get lost if 2.0 and 2.1 docs are generated from a common
> source.
Folks, do you know that there's the possibility to alias certain subparts of
a particular CVS repository from another repository?
Like "cocoon-2.1/src/docs" can be stored in the "cocoon-docs" repository.
Apache does it already with its httpd-docs repository, aliased to
httpd-2.0/docs (or something like it)...
Pier
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Jeff Turner <je...@apache.org>.
On Mon, Mar 24, 2003 at 07:31:39AM +0100, Steven Noels wrote:
> In order to get one little step closer to the 'new' document
> infrastructure, many of us seek clarity whether we should move docs to a
> separate CVS module or not. The benefits and downfalls are largely
> known, so let's vote on this and get this issue cleared.
>
> My own personal bias: don't forget the different Cocoon _versions_ are
> now stored in separate modules, too.
>
> Please cast your vote:
>
[ ] creation of cocoon-docs module
[+1] docs should stay in src/documentation of the code tree module(s)
Because:
- With a separate cocoon-docs module, I don't see how the various
code-related files (status.xml, jars.xml) are obtained.
- Making a separate doc module kills outright any future efforts to
generate docs directly from code (e.g. a component manual).
- I think that by default, doc changes should only apply to one codebase
(2.0 or 2.1). There are many differences that are *meant* to be there,
that could get lost if 2.0 and 2.1 docs are generated from a common
source.
--Jeff
> Cheers,
>
> </Steven>
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Christian Haul <ha...@dvs1.informatik.tu-darmstadt.de>.
On 24.Mar.2003 -- 07:31 AM, Steven Noels wrote:
> In order to get one little step closer to the 'new' document
> infrastructure, many of us seek clarity whether we should move docs to a
> separate CVS module or not. The benefits and downfalls are largely
> known, so let's vote on this and get this issue cleared.
>
> My own personal bias: don't forget the different Cocoon _versions_ are
> now stored in separate modules, too.
>
> Please cast your vote:
>
> [+0.5] creation of cocoon-docs module
> [ ] docs should stay in src/documentation of the code tree module(s)
Generating component docs from the source is a point to watch,
though. It would be great to have that OTOH I personally see the
(possibly improved) javadocs as component docs.
Chris.
--
C h r i s t i a n H a u l
haul@informatik.tu-darmstadt.de
fingerprint: 99B0 1D9D 7919 644A 4837 7D73 FEF9 6856 335A 9E08
tallying [Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module]
Posted by Steven Noels <st...@outerthought.org>.
(follow up to cocoon-docs please)
On 24/03/2003 7:31 Steven Noels wrote:
> In order to get one little step closer to the 'new' document
> infrastructure, many of us seek clarity whether we should move docs to a
> separate CVS module or not. The benefits and downfalls are largely
> known, so let's vote on this and get this issue cleared.
>
> My own personal bias: don't forget the different Cocoon _versions_ are
> now stored in separate modules, too.
>
> Please cast your vote:
results so far:
[ ] creation of cocoon-docs module: morrijr, shannon, stefano,
bdelacretaz
not sure because of comments: sylvain
not sure because of 0.x vote: haul
not eligible but almost a committer: andrew
[ ] docs should stay in src/documentation of the code tree
module(s): jefft, nicolaken, pier, stephan
... which means we could use some more votes do establish genuine
consensus...!
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Jeff Turner <je...@apache.org>.
On Mon, Mar 24, 2003 at 07:31:39AM +0100, Steven Noels wrote:
> In order to get one little step closer to the 'new' document
> infrastructure, many of us seek clarity whether we should move docs to a
> separate CVS module or not. The benefits and downfalls are largely
> known, so let's vote on this and get this issue cleared.
>
> My own personal bias: don't forget the different Cocoon _versions_ are
> now stored in separate modules, too.
>
> Please cast your vote:
>
[ ] creation of cocoon-docs module
[+1] docs should stay in src/documentation of the code tree module(s)
Because:
- With a separate cocoon-docs module, I don't see how the various
code-related files (status.xml, jars.xml) are obtained.
- Making a separate doc module kills outright any future efforts to
generate docs directly from code (e.g. a component manual).
- I think that by default, doc changes should only apply to one codebase
(2.0 or 2.1). There are many differences that are *meant* to be there,
that could get lost if 2.0 and 2.1 docs are generated from a common
source.
--Jeff
> Cheers,
>
> </Steven>
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
>
> Please cast your vote:
>
> [ +1 ] creation of cocoon-docs module
> [ -0 ] docs should stay in src/documentation of the code tree
> module(s)
I prefer a separate cocoon-docs module but do not find this terribly
important (assuming a tagged or released version of Forrest is used to
generate the docs, instead of being stored in our CVS as suggested
before).
-Bertrand
Re: [vote] micro-decision for docs: creation of cocoon-docs CVS
module
Posted by Stephan Michels <st...@apache.org>.
On Mon, 24 Mar 2003, Steven Noels wrote:
> In order to get one little step closer to the 'new' document
> infrastructure, many of us seek clarity whether we should move docs to a
> separate CVS module or not. The benefits and downfalls are largely
> known, so let's vote on this and get this issue cleared.
>
> My own personal bias: don't forget the different Cocoon _versions_ are
> now stored in separate modules, too.
>
> Please cast your vote:
>
> [ ] creation of cocoon-docs module
> [ X ] docs should stay in src/documentation of the code tree module(s)
Stephan.
RE: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by John Morrison <jo...@ntlworld.com>.
> From: Steven Noels [mailto:stevenn@outerthought.org]
>
> In order to get one little step closer to the 'new' document
> infrastructure, many of us seek clarity whether we should move docs to a
> separate CVS module or not. The benefits and downfalls are largely
> known, so let's vote on this and get this issue cleared.
>
> My own personal bias: don't forget the different Cocoon _versions_ are
> now stored in separate modules, too.
>
> Please cast your vote:
[ X ] creation of cocoon-docs module
[ ] docs should stay in src/documentation of the code tree module(s)
J.