You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@cocoon.apache.org by David Leangen <dl...@canada.com> on 2004/11/13 05:36:20 UTC
New documentation project? (was: [OT] This is quite disappointing...)
I started using Cocoon about a year ago now, just a little before Derek
Hohls. Even then, we were discussing the Cocoon doc.
For example:
http://marc.theaimsgroup.com/?l=xml-cocoon-users&m=108365757316657&w=2
I've been out of the project now for several months due to other
obligations, but I'll be back very soon.
Anyway, my 2 Yen based on previous experience is that Cocoon is too far
advanced and has therefore built up a lot of momentum, for better and for
worse. There would have to be a lot of effort to make any major changes to
the documentation. These efforts would be very time consuming due to all the
interests involved with so many good people in the project.
Derek's idea about outsourcing this is good, but (1) I'm not sure how
something like this could be financed and (2) it doesn't solve the problem
of getting agreement from all the various parties as to what the final
product should be.
So, to hopefully get this accomplished in practice, my suggestion would be
to start a new project (or maybe a Cocoon subproject), with fresh people who
are motivated by this idea and who aren't subject to veto (whether actually
or just by mere suggestion) by the "traditional" members. That way, I think
everybody would be happy.
On the one hand, it will be an opportunity to try something new. The people
involved in the new documentation project will have the freedom to make the
decisions they want and structure the documentation however they want, right
from the ground up.
On the other hand, they won't be stepping on anybody's toes. The more
established members who have been putting countless hours into the project,
who know this baby almost bit by bit, don't have to worry about things going
the wrong way because it doesn't _directly_ touch the Cocoon stuff. If later
they feel that the new doc is working out, then they can think about
integrating it into the main Cocoon project, but there would be no
obligation to do so.
But then again, this is a huge project and would require some very dedicated
people who, as Derek pointed out, have the skill set to accomplish this. I'm
not sure if these people actually exist...
Not sure if I'm making myself clear, but I'm interested in hearing others'
thoughts on this approach.
In any case, if somebody (Derek??) has the motivation to go ahead and take
the lead with this, I'd certainly be willing to participate. I've done a few
documentation projects, so I could help contribute some ideas and direction
to the process.
Dave
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: New documentation project?
Posted by Tony Collen <co...@umn.edu>.
David Leangen wrote:
> Just a thought, but why not get something started yourself on a place like
> SourceForge and, if it shows promise, you could then lobby for a place in
> Apache?
Dave,
There's a lot more to it than just this. A bunch of the people who are
working on it are committers, (myself included), so I think we're a
little more biased towards using existing Apache resources. I would
also expect some progress with respect to docs editing soon anyway. I
would suggest bringing this up on the -dev list if you're serious about
suggesting some alternatives -- most of the discussion about any work on
the docs happens there, and that would be the place to watch for
announcements of anything "new" happening.
Tony
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
RE: New documentation project?
Posted by David Leangen <dl...@canada.com>.
> I brought something up like this a month or two ago, over on the dev
> list I think, and my idea was to start up a Cocoon Shop Manual kind of
> thing. I guess one thing we were all waiting for was to have a system
> on apache.org that we can run an instance of Cocoon and Forrest on.
>
> I'm curious as to where the status of getting a VMWare host for us to
> run stuff on.
Oh, interesting!
I'm not sure how places like SourceForge work, but couldn't that be used, at
leat in the meantime? Is it necessary that the project begin in the Apache
infrastructure?
What you are suggesting is a case in point. The project isn't even getting
started due to various contraints and dependencies on others.
Just a thought, but why not get something started yourself on a place like
SourceForge and, if it shows promise, you could then lobby for a place in
Apache?
Regards,
Dave
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: New documentation project?
Posted by Tony Collen <co...@umn.edu>.
David Leangen wrote:
> I started using Cocoon about a year ago now, just a little before Derek
> Hohls. Even then, we were discussing the Cocoon doc.
>
> For example:
> http://marc.theaimsgroup.com/?l=xml-cocoon-users&m=108365757316657&w=2
>
>
> I've been out of the project now for several months due to other
> obligations, but I'll be back very soon.
<snip>
> But then again, this is a huge project and would require some very dedicated
> people who, as Derek pointed out, have the skill set to accomplish this. I'm
> not sure if these people actually exist...
>
>
> Not sure if I'm making myself clear, but I'm interested in hearing others'
> thoughts on this approach.
>
> In any case, if somebody (Derek??) has the motivation to go ahead and take
> the lead with this, I'd certainly be willing to participate. I've done a few
> documentation projects, so I could help contribute some ideas and direction
> to the process.
David,
I brought something up like this a month or two ago, over on the dev
list I think, and my idea was to start up a Cocoon Shop Manual kind of
thing. I guess one thing we were all waiting for was to have a system
on apache.org that we can run an instance of Cocoon and Forrest on.
I'm curious as to where the status of getting a VMWare host for us to
run stuff on.
Tony
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: How start?
Posted by Ralph Goers <Ra...@dslextreme.com>.
javascript wrote:
> Hello list,
> I am starting to work to a e-learning platform for a test plan.
> The structure will use the coplets and I am trying to use the two
> examples included in the documentation (portale and portale-portal-fw).
> The second example it is more complete but it seems to be slow, the
> first one seems better, but it is incomplete (there is not a
> management console).
>
> The plan is much simple (Portal+CMS+SCORM) and not there are members
> of JSP (JSR168 is not important).
> Can someone suggest to me if it is better to begin with portal or with
> portal-fw?
>
Use the Portal. The portal-fw will be deprecated in 2.1.6 and will
disappear in a future release.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: How start?
Posted by Nick Goupinets <ng...@openskysolutions.ca>.
Hi Ilario,
I hope I am not mistaken and the thing under consideration is whether to
use portal engine or portal framework.
I guess the answer will be: it depends.
Portal framework is a "vertical portal". At any point in time there is
only one page (that you can customize) with coplets. It is true that
there is a nice interface for adding and removing coplets and as well as
for user management. But it lacks a lot of very useful features: support
for multiple tabs, skins, extensible authentication mechanism.
Portal engine is a fully functional portal, not limited to just a single
vertical layout. If in your project you will ever need multiple pages
with different coplets presented, it would be reasonable to employ the
portal engine.
Of course, there are some limitations of portal engine. As you said, it
lacks the user management and coplet customization support, but these
functions can be implemented with a bit of work (user management is
easier to implement, coplet customization is slightly harder).
Sincerely,
Nick.
javascript wrote:
> Hello list,
> I am starting to work to a e-learning platform for a test plan.
> The structure will use the coplets and I am trying to use the two
> examples included in the documentation (portale and portale-portal-fw).
> The second example it is more complete but it seems to be slow, the
> first one seems better, but it is incomplete (there is not a management
> console).
>
> The plan is much simple (Portal+CMS+SCORM) and not there are members of
> JSP (JSR168 is not important).
> Can someone suggest to me if it is better to begin with portal or with
> portal-fw?
>
> Thanks
>
> Ilario
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
> For additional commands, e-mail: users-help@cocoon.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
How start?
Posted by javascript <ja...@tin.it>.
Hello list,
I am starting to work to a e-learning platform for a test plan.
The structure will use the coplets and I am trying to use the two
examples included in the documentation (portale and portale-portal-fw).
The second example it is more complete but it seems to be slow, the
first one seems better, but it is incomplete (there is not a management
console).
The plan is much simple (Portal+CMS+SCORM) and not there are members of
JSP (JSR168 is not important).
Can someone suggest to me if it is better to begin with portal or with
portal-fw?
Thanks
Ilario
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: bored with *talks* about docs (was: New documentation project?)
Posted by beyaNet <an...@jibeya.com>.
Bertrand,
I'm inclined to agree with your point of view. The community knows that
things can be improved in terms of documenting cocoon so let's, instead
of having the mother of all discussions about the blatantly
self-evident, now concentrate on putting some flesh on this discussion.
regards
Andrew
p.s. just had 2 hours sleep!!
On 13 Nov 2004, at 11:31, Bertrand Delacretaz wrote:
> Le 13 nov. 04, à 05:36, David Leangen a écrit :
>
>> ...Not sure if I'm making myself clear, but I'm interested in hearing
>> others'
>> thoughts on this approach...
>
> You might want to take what follows with a grain of salt, please don't
> be offended.
>
> (First a bit of context to help you understand: it's a grey saturday
> morning here, I went to bed too late, I have a bit of flu and I've
> been feeling bad about Cocoon docs for at least two years without
> really being able to do much to improve it. Now the stage is set: old
> grumpy man here ;-)
>
> So here we go: I'm a bit bored about all these discussions about our
> docs. Yes, we know our docs are suboptimal.
>
> Problem is, every now and then, people (myself included, I've been
> guitly of this *several times* actually ;-) come up with bright new
> ideas about improving our docs, lots of really interesting talks,
> but...nothing really happens.
>
> I think it's the same with code or docs or everything: we could talk
> for ages about the best way of doing things, but unless actual,
> concrete, real, tangible stuff happens, it's just talk.
>
> Do you want better docs? Fine, so do I, so do most people here.
> I'd love to have more time to work on them - I don't, so is life for
> me at this point unfortunately.
>
> Do you have resources to make it happen, or at least create a
> reasonably-sized "seed" of what the new docs could be? Then go for it!
> This will make all the difference.
>
> Don't ask around too much, you know the need and will is here - just
> do it, import the good parts of the existing docs (there *are* quite a
> lot of good parts actualy hidden in there) into whatever system you
> feel is good to use, create a live, tangible, concrete example of what
> the new docs will be and *convince people* that it's the way to go -
> by *showing them* the actual thing, flesh and bones.
>
> Our wiki, even with all its flaws, has shown that this can work and be
> an improvement: things were much worse before we had the wiki. Some
> people created it (a long time ago ;-), put initial content in it,
> this convinced others that it was a Good Thing and people started
> added content to it. It worked. To a point, but it's been a big
> improvement already.
>
> I'm not saying that our wiki is fantastic, but the *process* of
> planting an initial seed has worked once - let's make it work once
> again.
>
> Once again, don't get me wrong: I'm talking to myself here as much as
> to everybody else, but I hope you get the point: you have good ideas
> for our docs: then just go for it!
>
> Hope this helps..
>
> -Bertrand
>
Re: bored with *talks* about docs (was: New documentation project?)
Posted by Bertrand Delacretaz <bd...@apache.org>.
Le 13 nov. 04, à 12:44, David Leangen a écrit :
> .. - can we have our own mailing list?..
don't think people would be offended if you discuss this here, maybe
with a suitable header like [NEWDOCS] in the subject so people can
filter it out if they want.
In this way you'd have more visibility here, and more people could join
the effort.
-Bertrand
Re: bored with *talks* about docs (was: New documentation project?)
Posted by Upayavira <uv...@upaya.co.uk>.
beyaNet wrote:
> David,
> time permitting, I would like to put my name forward.
>
> 'Cocoon - how do I?'
Great! As I said to David, why don't you take a look at
http://wiki.apache.org/cocoon/Cocoon215TOC and see if there are any gaps
you could fill in? The more of us work on this, the more we'll see happen.
Regards, Upayavira
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: bored with *talks* about docs (was: New documentation project?)
Posted by beyaNet <an...@jibeya.com>.
David,
time permitting, I would like to put my name forward.
'Cocoon - how do I?'
regards
Andrew
On 13 Nov 2004, at 11:44, David Leangen wrote:
>
>> Don't ask around too much, you know the need and will is here - just
>> do
>> it, import the good parts of the existing docs (there *are* quite a
>> lot
>> of good parts actualy hidden in there) into whatever system you feel
>> is
>> good to use, create a live, tangible, concrete example of what the new
>> docs will be and *convince people* that it's the way to go - by
>> *showing them* the actual thing, flesh and bones.
>
>
> Know what... come to think of it, I may just take you up on your
> challenge,
> even though time is limited.
>
> So, my first questions are:
>
> - who else is interested in joining this subproject?
>
> - can we have our own mailing list?
>
>
> My actions will depend on the answers to these first questions.
>
>
> Regards,
> Dave
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
> For additional commands, e-mail: users-help@cocoon.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: bored with *talks* about docs (was: New documentation project?)
Posted by Bertrand Delacretaz <bd...@apache.org>.
Le 13 nov. 04, à 14:21, Upayavira a écrit :
> ...You see, I think this will happen best if we use what we've got,
> and start small, rather than trying to create something new. The wiki
> isn't hard to use, and anyone who wants to can participate...
+1, and the formats used today (xdocs and wiki) can be moved to any
other format or system fairly easily if needed anyway, so you're very
right that the first thing is to work on the content!
-Bertrand
Suggestion: (To Wiki, or not to Wiki (was: bored with *talks* about docs))
Posted by Yves Vindevogel <yv...@implements.be>.
Hi,
I have a little suggestion for the docs ...
Why not use the same method as the people at JBoss ?
AFAIK, their documentation is up-to-date.
They wrote down all the docs, and published them in books. I think
that brought in enough money to pay for writing the docs in the first
place.
Most of us will find it a fair way to contribute financially: buy the
book with the latest documentation.
I know some books are on the market today, I have 2 (I think), but I
think they were not really sold by the community, AFAIK.
My 2 cents
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: To Wiki, or not to Wiki (was: bored with *talks* about docs)
Posted by beyaNet <an...@jibeya.com>.
David,
that would be a good starting point. Once we have a starting point we
can than take things from there....
regards
Andrew
On 13 Nov 2004, at 14:21, Bertrand Delacretaz wrote:
> Le 13 nov. 04, à 14:59, David Leangen a écrit :
>> ...Anyway, if you still want to hear about what I think, perhaps I
>> could make a
>> separate wiki that gives a bit of an idea of my vision. The best that
>> could
>> happen is you'll see some things you like and we'll be able to find a
>> good
>> compromise. The worst that could happen is that you can decide that
>> you
>> don't like my approach and politely tell me to bugger off. ;-)
>
> Sounds good to me - showing us your vision as actual documents is
> certainly the best, and where this happens is not really important
> IMHO.
>
> Note that you could do it on the current wiki, for example by
> prefixing all your page names with the same prefix to make them easily
> recognizable. But if you prefer to create this seed elsewhere, I don't
> see a problem.
>
> You might meet some skepticism here, mostly because there have been
> several such experiments in the past, which have all stopped after a
> few weeks as the initial excitement disappeared. But we're (at least
> I'm) all ears and eyes if you can do better!
>
> -Bertrand
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
RE: To Wiki, or not to Wiki
Posted by David Leangen <dl...@canada.com>.
> You might meet some skepticism here, mostly because there have been
> several such experiments in the past, which have all stopped after a
> few weeks as the initial excitement disappeared. But we're (at least
> I'm) all ears and eyes if you can do better!
Well, what I and those who join me could do is make our proposal and, if it
is rejected by the Cocoon community, spin it off into a commercial-type
project.
Or something like that.
Who knows, maybe this type of work is better suited to the commercial model
to begin with...
Cheers,
Dave
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: To Wiki, or not to Wiki (was: bored with *talks* about docs)
Posted by Bertrand Delacretaz <bd...@apache.org>.
Le 13 nov. 04, à 14:59, David Leangen a écrit :
> ...Anyway, if you still want to hear about what I think, perhaps I
> could make a
> separate wiki that gives a bit of an idea of my vision. The best that
> could
> happen is you'll see some things you like and we'll be able to find a
> good
> compromise. The worst that could happen is that you can decide that you
> don't like my approach and politely tell me to bugger off. ;-)
Sounds good to me - showing us your vision as actual documents is
certainly the best, and where this happens is not really important
IMHO.
Note that you could do it on the current wiki, for example by prefixing
all your page names with the same prefix to make them easily
recognizable. But if you prefer to create this seed elsewhere, I don't
see a problem.
You might meet some skepticism here, mostly because there have been
several such experiments in the past, which have all stopped after a
few weeks as the initial excitement disappeared. But we're (at least
I'm) all ears and eyes if you can do better!
-Bertrand
To Wiki, or not to Wiki (was: bored with *talks* about docs)
Posted by David Leangen <dl...@canada.com>.
> There's a huge amount you can contribute to this effort I'm sure. All it
> needs is people like you on board!
Thank you for your nice compliments. I wouldn't speak so quickly, though.
You haven't yet experienced how opinionated I really am. ;-)
> How does that sit with you?
I think you have many great ideas. My main worry is that my "vision" is just
too different, and I would likely cause more friction and discordance than
actually help the process. I suppose that I am one of those people best
suited for new projects rather than joining in projects well under way.
Also, although I have a technical background and recently have been doing
almost 100% development, my main experience is more on the business side of
things. To be blunt, the business approach is very different and so
incompatible with the scientific/engineering mindset that it is very rare
that tekkies can successfully cross over. For instance, thinking logically,
which comes oh, so naturally for us programmers, can actually do more harm
than good when dealing with people and customers. I now accept this as
"fact" though I often have trouble acting accordingly.
I say all this because I think that my way of doing things is just too
different from what would be accepted by Cocoon members. Cocoon is an
organisation made by tekkies, for tekkies.
The reason I think that your suggested approach is faulty is because it's
starting from what we already have. Well, what we already have has mostly
been developer-centric. Rather, we need to be more user-centric. The process
should be starting off with "who is the user and what does he/she/it
want/need to know?" As a concrete example, I think that we can do away with
(completely or almost completely) the "history" section. Is this useful for
understanding Cocoon, evaluating if it's worth the risk for me (assuming
we're dealing with a business, which I assume most users are) to invest my
company's time? Does this help me to get up and running? Does this answer
the concerns I have about how using Cocoon will affect my business? The
answer is "no". So the action should be "delete".
See now why I would just cause more debate than help move the project along?
Anyway, if you still want to hear about what I think, perhaps I could make a
separate wiki that gives a bit of an idea of my vision. The best that could
happen is you'll see some things you like and we'll be able to find a good
compromise. The worst that could happen is that you can decide that you
don't like my approach and politely tell me to bugger off. ;-)
WDYT?
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: bored with *talks* about docs (was: New documentation project?)
Posted by Upayavira <uv...@upaya.co.uk>.
David Leangen wrote:
>>Don't ask around too much, you know the need and will is here - just do
>>it, import the good parts of the existing docs (there *are* quite a lot
>>of good parts actualy hidden in there) into whatever system you feel is
>>good to use, create a live, tangible, concrete example of what the new
>>docs will be and *convince people* that it's the way to go - by
>>*showing them* the actual thing, flesh and bones.
>>
>>
>
>
>Know what... come to think of it, I may just take you up on your challenge,
>even though time is limited.
>
>So, my first questions are:
>
> - who else is interested in joining this subproject?
>
> - can we have our own mailing list?
>
>
>My actions will depend on the answers to these first questions.
>
>
We could set up a separate subproject - or we could just start on the
wiki. I've referred to the wiki.apache.org/cocoon/Cocoon215TOC page,
which is a previous attempt at doc improvement. Could you take a look at
that, and either add come content to it (by adding additional pages), or
find existing material and linking to it?
You see, I think this will happen best if we use what we've got, and
start small, rather than trying to create something new. The wiki isn't
hard to use, and anyone who wants to can participate.
As Bertrand said, there'll be much more visibility (and possible
participation) if we discuss this here.
How does that sit with you?
There's a huge amount you can contribute to this effort I'm sure. All it
needs is people like you on board!
Regards, Upayavira
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
RE: bored with *talks* about docs (was: New documentation project?)
Posted by David Leangen <dl...@canada.com>.
> Don't ask around too much, you know the need and will is here - just do
> it, import the good parts of the existing docs (there *are* quite a lot
> of good parts actualy hidden in there) into whatever system you feel is
> good to use, create a live, tangible, concrete example of what the new
> docs will be and *convince people* that it's the way to go - by
> *showing them* the actual thing, flesh and bones.
Know what... come to think of it, I may just take you up on your challenge,
even though time is limited.
So, my first questions are:
- who else is interested in joining this subproject?
- can we have our own mailing list?
My actions will depend on the answers to these first questions.
Regards,
Dave
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: bored with *talks* about docs (was: New documentation project?)
Posted by Bertrand Delacretaz <bd...@apache.org>.
Le 13 nov. 04, à 12:39, David Leangen a écrit :
> ...(Also, intentionally or not, appears to support the idea of
> starting this
> out as a new, smaller project...)
Starting outside might be a good idea to experiment freely - but for
me, assuming good stuff comes out of this "docs fork", it should move
here quickly to avoid fragmentation and gain full support of this
community.
We do the same for code: there's a scratchpad where people are
encouraged to try whatever they want to try, but the aim is for stuff
there to be good enough to move into the main code tree.
-Bertrand
RE: bored with *talks* about docs (was: New documentation project?)
Posted by David Leangen <dl...@canada.com>.
> > ...Not sure if I'm making myself clear, but I'm interested in hearing
> > others' thoughts on this approach...
>
> You might want to take what follows with a grain of salt, please don't
> be offended.
Not offended at all. Good points and well said! :-)
(Also, intentionally or not, appears to support the idea of starting this
out as a new, smaller project...)
Dave
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
bored with *talks* about docs (was: New documentation project?)
Posted by Bertrand Delacretaz <bd...@apache.org>.
Le 13 nov. 04, à 05:36, David Leangen a écrit :
> ...Not sure if I'm making myself clear, but I'm interested in hearing
> others'
> thoughts on this approach...
You might want to take what follows with a grain of salt, please don't
be offended.
(First a bit of context to help you understand: it's a grey saturday
morning here, I went to bed too late, I have a bit of flu and I've been
feeling bad about Cocoon docs for at least two years without really
being able to do much to improve it. Now the stage is set: old grumpy
man here ;-)
So here we go: I'm a bit bored about all these discussions about our
docs. Yes, we know our docs are suboptimal.
Problem is, every now and then, people (myself included, I've been
guitly of this *several times* actually ;-) come up with bright new
ideas about improving our docs, lots of really interesting talks,
but...nothing really happens.
I think it's the same with code or docs or everything: we could talk
for ages about the best way of doing things, but unless actual,
concrete, real, tangible stuff happens, it's just talk.
Do you want better docs? Fine, so do I, so do most people here.
I'd love to have more time to work on them - I don't, so is life for me
at this point unfortunately.
Do you have resources to make it happen, or at least create a
reasonably-sized "seed" of what the new docs could be? Then go for it!
This will make all the difference.
Don't ask around too much, you know the need and will is here - just do
it, import the good parts of the existing docs (there *are* quite a lot
of good parts actualy hidden in there) into whatever system you feel is
good to use, create a live, tangible, concrete example of what the new
docs will be and *convince people* that it's the way to go - by
*showing them* the actual thing, flesh and bones.
Our wiki, even with all its flaws, has shown that this can work and be
an improvement: things were much worse before we had the wiki. Some
people created it (a long time ago ;-), put initial content in it, this
convinced others that it was a Good Thing and people started added
content to it. It worked. To a point, but it's been a big improvement
already.
I'm not saying that our wiki is fantastic, but the *process* of
planting an initial seed has worked once - let's make it work once
again.
Once again, don't get me wrong: I'm talking to myself here as much as
to everybody else, but I hope you get the point: you have good ideas
for our docs: then just go for it!
Hope this helps..
-Bertrand
Re: New documentation project?
Posted by Upayavira <uv...@upaya.co.uk>.
David Leangen wrote:
>Hi, Upayavira.
>
>First, I want to express my thanks for all your efforts, and those like you.
>You have always been very active on this list and have helped me on several
>occasions. Thanks!
>
>Second, I want to stress that my post was in NO WAY intended to be negative
>towards anybody. I very much respect the efforts of all the individuals who
>contribute to the project. I was merely trying to point out some kind of
>practical solution. I hope that you or anybody else did not see it as a
>negative criticism.
>
>
Rest assured, I never took it that way. I know there's something wrong,
and I want to understand more what we can do to improve things.
Understanding others' perspectives can only help.
>Ok, so with that out of the way, here is the reply to your questions.
>
>
>>Can you explain more what you mean here? Obviously you feel that
>>'traditional members' are 'blocking' the creation of documentation
>>somehow. Can you explain more how you perceive this? I am _very_
>>interested to understand..
>>
>>
>
>This is not exactly what I was trying to express. Again, I must stress that
>my comments are not intended to be negative. I am just trying to make some
>observations in the hope of being helpful. :-)
>
>I think that there are two issues here. The first is that in addition to the
>actual hierarchy, there is a kind of de facto hierarchy in the project.
>Officially, on the top is the PMC, then the committers, then the users.
>Unofficially, there is the project founders, then the very active
>contributors, then the not-so-active committers, then the active users, then
>the "newbies" and others. I think that there is a kind of natural tendency
>to revere the project founders and active committers, so that even if they
>do not actively "block" any attempt at a new direction in terms of
>documentation, their say in the project has--as a natural course--more
>weight. If it weren't this way, the project would be chaotic, so this kind
>of natural and subtle hierarchy is necessary. The unfortunate side-effect,
>however, is that it can in some cases stiffle new ideas, which is what may
>be happening in terms of the documentation.
>
>
You know something - I find this utterly fascinating. You may have
noticed my name. It is my Buddhist name. I am a member of the Western
Buddhist Order. This order, and its associated Buddhist movement,
functions as a meritocracy. There are often frustrations expressed about
how this movement works, and how it blocks creativity, when its very
existence is about facilitiating creativity. Now, the funny thing is, if
I replaced every reference in the above paragraph to Cocoon with a
reference to this Buddhist movement, it would still make sense.
So, what I deduce from this is that the above concerns are in some way
inherent in meritocracies, which is exactly what Apache, and thus
Cocoon, is.
People 'below' in the meritocratic hierarchy feel blocked and stifled by
those 'higher', when those 'higher' don't perceive themselves as doing
anything to cause such a block.
In fact, a lot of this has to do with the fact that, in a meritocractic
society, it takes time for people to learn how that society functions,
and takes time to become an effective member of that society. It is
necessary to have some understanding of that society in order to really
effect change within it. And for those that don't yet have that
understanding, or don't feel that they do, that can be very frustrating.
And when those 'higher' try to explain how the society works, it can
appear as if they are 'blocking'. In fact, they are usually trying to
draw people in, to explain that which needs to be known before effective
change can happen. However, it often doesn't come across that way.
The other side of meritocratic society is that people are very often
volunteers. Those 'lower' come to have expectations of how those
'higher' should behave (e.g. replying promptly to questions on mailing
lists, fixing bugs quickly, or giving time to newcomers to a Buddhist
movement who are having a difficult time...), but those 'higher' are
often busy, lacking in time, or lacking in emotional or other resources
to do justice to that which they themselves aspire to do.
A newcomer says, "I want to get involved". Someone involved says, "then
do this to help me". The newcomer says, "okay, look at this for me", the
involved person says, "ah, I'd love to, but I don't have time". Bingo. A
block.
It seems to me that the people who actually manage to get involved with
Apache are those who manage to get to grips with what a meritocracy is
and how it works. It is a simple process really:
* act. Do something constructive. Contribute (wiki, code/doc patches
for SVN, etc)
* keep going
* your positive contribution is noticed
* at some point, that contribution is recognised, and you are given
access to the repository.
And I really don't see why this can't happen more, and for people who
are only interested in documentation (i.e. non-coders).
>As one practical example, you'll notice that when a new user makes a post to
>the list, he/she inevitably begins with "I'm only a newbie, but..." as if to
>apologise.
>
>As another practical example, let's take a suggestion I made several months
>ago, to which somebody (I don't remember who, and it's not important for the
>example anyway) replied. Oh, and please do not reply to this example, as it
>is only indended to explain what I mean and not to spark any kind of debate
>on the content of the example itself.
>
>I suggested that we should think of a new "positioning statement" for the
>Cocoon project. Current, we say something to the effect of "Cocoon is a type
>of glue for your web applications". This is very true, indeed. The problem,
>however, IMNSHO, is that this type of statement is very ineffective for
>communicating Cocoon to people who do not know the project. This type of
>branding must immediately make the listener understand what the project is
>about. The problem with the current statement is that the first reaction of
>the reader is... "huh?" My argument was that unfortunately, in most cases,
>when people can't connect with the product, when they don't understand, they
>will move on and, for instance... use Struts. The committer in question
>replied by very simply saying "I think this is fine." No veto and no
>blocking: just stating a very valid opinion. In practice, however, unless
>the proposer of the new idea is extremely motivated or simply insensitive to
>the opinions of the Cocoon veterans, this _does_ block the process.
>
>
>
>The more important issue, however, is that the committers are in too deep.
>The cannot have the same perception as new users since they are not at all
>on the same point of the learning curve. I think that even for the best of
>us, it is really difficult to really, truly emphasise with new users when
>we're so far ahead. So, despite the best efforts of the active committers, I
>think that by nature they are not well suited for the job. They can act as
>references and advisors, certainly! However, except for very exceptional
>cases, I generally think that they would not make good project leads.
>
>Then, as Derek pointed out, except for rare cases, developers are generally
>not great writers. Hey, we're too "smart" for that kind of mundane work. ;-)
>
>
I totally agree. However, as I have heard said elsewhere, "committer"
refers to "commitment to Cocoon" rather than to "coding" for Cocoon.
There are one or two active committers who have never, to my knowledge,
committed anything.
I'd love to see us having a new breed of committer that wants to work
with the coders (as described so well in Ralph's reply to your message)
to improve the quality documentation. I will do what I can to make this
happen. And I am willing to offer some suggestions and practical help in
getting this to work within the context of the Apache meritocratic system.
>>Are you suggesting that you would feel worried about having full commit
>>access to Cocoon and would prefer to have it on just documentation? Or
>>are you suggesting that you think 'traditional members' would prefer it
>>if you had that sort of access?
>>
>>
>
>That is not what I was intending to say, but I will however reply to this,
>speaking only for myself, of course.
>
>I would not feel uncomfortable having full commit status because I would use
>that status responsibly. I would not, however, feel comfortable actually
>committing code. The reason is that the active committers are such strong
>developers and are so far ahead on the learning curve that I would feel very
>much out of place and perhaps a bit intimidated. I'm wondering if this isn't
>so for others as well...
>
>
Okay. That is very useful for me to hear. I would love to hear if others
feel the same or would prefer not to have commit access to code.
>In terms of the documentation, however, I would gladly commit, though my
>opinions and views would surely inspire at least a dozen opposing views, as
>I'll discuss below.
>
>
I'm sure!
>>I'm very interested in hearing more from your side. I know a lot about
>>the 'traditional' way of doing things, and obviously, right now, it
>>isn't working, so we need to do something else.
>>
>>
>
>One of the problems is that the community has become too large. This means
>that there are too many opposing views. I think that it is no longer
>possible to reach any consensus easily. I believe, based on your posts as
>well as those of others that there is a willingness to work on
>documentation, so that's not the problem. The problem is getting everyone to
>agree.
>
>
In meritocracy, it is almost always possible to achieve some level of
concensus. My Order is struggling with this too (having reached 1000
members, with no formal power hierarchy within it at all).
As Stefano has said, Apache is a meritocracy from the outside, and a
'do-ocracy' from the inside. A do-ocracy is basically, "Those that do,
decide".
So, if some of us decide to do it, with the backing of some committers,
I suspect we will quite quickly get wholehearted backing.
Preparedness to act will be noticed.
>So, with all that in mind, this leads me to conclude that the most efficient
>approach would be to start afresh, seperately from the main Cocoon project,
>with a small core team of dedicated people. Once this new project or
>subproject reaches critical mass, it could then be reincorporated into the
>main project. By then, there will be enough momentum that the documentation
>should continue to head in the right direction.
>
>
That is one approach. My preferred approach is to start small, with
small incremental changes to what we have currently got. Starting with
the Wiki, where anyone can participate. If we pull the content on the
wiki together (see http://wiki.apache.org/cocoon/Cocoon215TOC for a good
place to start), we can start to build a good body of content - cut our
teeth on something safe. Then, if we want, we can move some or all of
that content across to the main Subversion repository at a later stage.
>>So you don't feel up to taking the lead, but do feel up to helping.
>>
>>
>
>Almost. I would love to take up the lead in such a project. However, I have
>too many time constraints. I believe that the lead has to have enough
>availability to tackle such a large and important project. So, I would
>instead gladly contribute to such project within these contraints.
>
>
As is the case with most of us! I hope/plan to help more with this, have
the enthusiasm and experience of Apache, but perhaps lack in knowledge
about documentation writing. If you're prepared to help, maybe we can
come up with something good.
I hope this missive is relevant and not to rambly!
Regards, Upayavira
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: New documentation project?
Posted by Upayavira <uv...@upaya.co.uk>.
Ralph Goers wrote:
> David Leangen wrote:
>
>> Agreed, but when applied to manuals.
>>
>> IMO, Cocoon needs much more than just a users' manual: it needs
>> educational
>> material. Also, to address the fundamental problems brought up by Derek
>> about the difficulty in getting Cocoon to go mainstream, this requires
>> skills in marketing, PR, project development... Essentially (and please
>> don't be angry with poor little me...) the whole website has to go.
>
> Well, I certainly won't get angry as I didn't design it. However, if
> I had I am sure it would be much worse...
>
>> So, I think that the skill set for this type of work is a little
>> different
>> from what you mention above.
>
> Could be. But the bottom line is that IMO it should not be a one man
> show, but should be a team that does things by consensus.
Yes, I'd love to see a team of us getting together here (or somewhere)
and starting to work on improving our documentation.
Consensus being one part of a meritocratic society, but not one that
need be frightening. Consensus often involves thos that don't do being
pleased and willing to accept the opinions and choices of those that do.
Regards, Upayavira
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: New documentation project?
Posted by Ralph Goers <Ra...@dslextreme.com>.
David Leangen wrote:
>
>Agreed, but when applied to manuals.
>
>IMO, Cocoon needs much more than just a users' manual: it needs educational
>material. Also, to address the fundamental problems brought up by Derek
>about the difficulty in getting Cocoon to go mainstream, this requires
>skills in marketing, PR, project development... Essentially (and please
>don't be angry with poor little me...) the whole website has to go.
>
>
Well, I certainly won't get angry as I didn't design it. However, if I
had I am sure it would be much worse...
>So, I think that the skill set for this type of work is a little different
>from what you mention above.
>
>
Could be. But the bottom line is that IMO it should not be a one man
show, but should be a team that does things by consensus.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
RE: New documentation project?
Posted by David Leangen <dl...@canada.com>.
Good points, Ralph.
Just one additional thought...
> My past experience has been that the best documentation comes from
> people who like to write and are technical enough that they can read
> small pieces of code and understand it. Basically, when I have worked
> with technical writers they ask for an "information dump" where the
> developer sends documentation in a very raw form. The writer then takes
> this information and formulates it into something that makes sense. This
> is a very iterative process as the writer frequently has to go back to
> the developer to get information.
Agreed, but when applied to manuals.
IMO, Cocoon needs much more than just a users' manual: it needs educational
material. Also, to address the fundamental problems brought up by Derek
about the difficulty in getting Cocoon to go mainstream, this requires
skills in marketing, PR, project development... Essentially (and please
don't be angry with poor little me...) the whole website has to go.
So, I think that the skill set for this type of work is a little different
from what you mention above.
Cheers,
Dave
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: New documentation project?
Posted by Ralph Goers <Ra...@dslextreme.com>.
David Leangen wrote:
>Then, as Derek pointed out, except for rare cases, developers are generally
>not great writers. Hey, we're too "smart" for that kind of mundane work. ;-)
>
>
I can't speak for everybody, but just for myself. I don't like writing
documents. I write well, but I do tend to go into things too deeply.
I've noticed that since English is not the native language for many of
my fellow committers that some of the documentation suffers from that.
>I would not feel uncomfortable having full commit status because I would use
>that status responsibly. I would not, however, feel comfortable actually
>committing code. The reason is that the active committers are such strong
>developers and are so far ahead on the learning curve that I would feel very
>much out of place and perhaps a bit intimidated. I'm wondering if this isn't
>so for others as well...
>
>In terms of the documentation, however, I would gladly commit, though my
>opinions and views would surely inspire at least a dozen opposing views, as
>I'll discuss below.
>
My past experience has been that the best documentation comes from
people who like to write and are technical enough that they can read
small pieces of code and understand it. Basically, when I have worked
with technical writers they ask for an "information dump" where the
developer sends documentation in a very raw form. The writer then takes
this information and formulates it into something that makes sense. This
is a very iterative process as the writer frequently has to go back to
the developer to get information.
It would be great if we had folks who wanted and were able to contribute
to Cocoon in this capacity. I'd certainly be in favor of giving tech
writers commit access to the subversion repository for the web site, if
that is possible. Frankly, the benefits to being a tech writer would be
huge, IMO. They would gain a deep understanding of Cocoon and could
possibly use that to their benefit in teaching others.
>>So you don't feel up to taking the lead, but do feel up to helping.
>>
>>
>
>Almost. I would love to take up the lead in such a project. However, I have
>too many time constraints. I believe that the lead has to have enough
>availability to tackle such a large and important project. So, I would
>instead gladly contribute to such project within these contraints.
>
>
Well, if it stays within Apache that wouldn't be a problem since the
"lead" is the consensus of the team.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
RE: New documentation project?
Posted by David Leangen <dl...@canada.com>.
Hi, Upayavira.
First, I want to express my thanks for all your efforts, and those like you.
You have always been very active on this list and have helped me on several
occasions. Thanks!
Second, I want to stress that my post was in NO WAY intended to be negative
towards anybody. I very much respect the efforts of all the individuals who
contribute to the project. I was merely trying to point out some kind of
practical solution. I hope that you or anybody else did not see it as a
negative criticism.
Ok, so with that out of the way, here is the reply to your questions.
> Can you explain more what you mean here? Obviously you feel that
> 'traditional members' are 'blocking' the creation of documentation
> somehow. Can you explain more how you perceive this? I am _very_
> interested to understand..
This is not exactly what I was trying to express. Again, I must stress that
my comments are not intended to be negative. I am just trying to make some
observations in the hope of being helpful. :-)
I think that there are two issues here. The first is that in addition to the
actual hierarchy, there is a kind of de facto hierarchy in the project.
Officially, on the top is the PMC, then the committers, then the users.
Unofficially, there is the project founders, then the very active
contributors, then the not-so-active committers, then the active users, then
the "newbies" and others. I think that there is a kind of natural tendency
to revere the project founders and active committers, so that even if they
do not actively "block" any attempt at a new direction in terms of
documentation, their say in the project has--as a natural course--more
weight. If it weren't this way, the project would be chaotic, so this kind
of natural and subtle hierarchy is necessary. The unfortunate side-effect,
however, is that it can in some cases stiffle new ideas, which is what may
be happening in terms of the documentation.
As one practical example, you'll notice that when a new user makes a post to
the list, he/she inevitably begins with "I'm only a newbie, but..." as if to
apologise.
As another practical example, let's take a suggestion I made several months
ago, to which somebody (I don't remember who, and it's not important for the
example anyway) replied. Oh, and please do not reply to this example, as it
is only indended to explain what I mean and not to spark any kind of debate
on the content of the example itself.
I suggested that we should think of a new "positioning statement" for the
Cocoon project. Current, we say something to the effect of "Cocoon is a type
of glue for your web applications". This is very true, indeed. The problem,
however, IMNSHO, is that this type of statement is very ineffective for
communicating Cocoon to people who do not know the project. This type of
branding must immediately make the listener understand what the project is
about. The problem with the current statement is that the first reaction of
the reader is... "huh?" My argument was that unfortunately, in most cases,
when people can't connect with the product, when they don't understand, they
will move on and, for instance... use Struts. The committer in question
replied by very simply saying "I think this is fine." No veto and no
blocking: just stating a very valid opinion. In practice, however, unless
the proposer of the new idea is extremely motivated or simply insensitive to
the opinions of the Cocoon veterans, this _does_ block the process.
The more important issue, however, is that the committers are in too deep.
The cannot have the same perception as new users since they are not at all
on the same point of the learning curve. I think that even for the best of
us, it is really difficult to really, truly emphasise with new users when
we're so far ahead. So, despite the best efforts of the active committers, I
think that by nature they are not well suited for the job. They can act as
references and advisors, certainly! However, except for very exceptional
cases, I generally think that they would not make good project leads.
Then, as Derek pointed out, except for rare cases, developers are generally
not great writers. Hey, we're too "smart" for that kind of mundane work. ;-)
> Are you suggesting that you would feel worried about having full commit
> access to Cocoon and would prefer to have it on just documentation? Or
> are you suggesting that you think 'traditional members' would prefer it
> if you had that sort of access?
That is not what I was intending to say, but I will however reply to this,
speaking only for myself, of course.
I would not feel uncomfortable having full commit status because I would use
that status responsibly. I would not, however, feel comfortable actually
committing code. The reason is that the active committers are such strong
developers and are so far ahead on the learning curve that I would feel very
much out of place and perhaps a bit intimidated. I'm wondering if this isn't
so for others as well...
In terms of the documentation, however, I would gladly commit, though my
opinions and views would surely inspire at least a dozen opposing views, as
I'll discuss below.
> I'm very interested in hearing more from your side. I know a lot about
> the 'traditional' way of doing things, and obviously, right now, it
> isn't working, so we need to do something else.
One of the problems is that the community has become too large. This means
that there are too many opposing views. I think that it is no longer
possible to reach any consensus easily. I believe, based on your posts as
well as those of others that there is a willingness to work on
documentation, so that's not the problem. The problem is getting everyone to
agree.
So, with all that in mind, this leads me to conclude that the most efficient
approach would be to start afresh, seperately from the main Cocoon project,
with a small core team of dedicated people. Once this new project or
subproject reaches critical mass, it could then be reincorporated into the
main project. By then, there will be enough momentum that the documentation
should continue to head in the right direction.
> So you don't feel up to taking the lead, but do feel up to helping.
Almost. I would love to take up the lead in such a project. However, I have
too many time constraints. I believe that the lead has to have enough
availability to tackle such a large and important project. So, I would
instead gladly contribute to such project within these contraints.
Regards,
Dave
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: New documentation project?
Posted by Upayavira <uv...@upaya.co.uk>.
David Leangen wrote:
>I started using Cocoon about a year ago now, just a little before Derek
>Hohls. Even then, we were discussing the Cocoon doc.
>
>For example:
>http://marc.theaimsgroup.com/?l=xml-cocoon-users&m=108365757316657&w=2
>
>
>I've been out of the project now for several months due to other
>obligations, but I'll be back very soon.
>
>
>Anyway, my 2 Yen based on previous experience is that Cocoon is too far
>advanced and has therefore built up a lot of momentum, for better and for
>worse. There would have to be a lot of effort to make any major changes to
>the documentation. These efforts would be very time consuming due to all the
>interests involved with so many good people in the project.
>
>Derek's idea about outsourcing this is good, but (1) I'm not sure how
>something like this could be financed and (2) it doesn't solve the problem
>of getting agreement from all the various parties as to what the final
>product should be.
>
>
>So, to hopefully get this accomplished in practice, my suggestion would be
>to start a new project (or maybe a Cocoon subproject), with fresh people who
>are motivated by this idea and who aren't subject to veto (whether actually
>or just by mere suggestion) by the "traditional" members. That way, I think
>everybody would be happy.
>
>
Can you explain more what you mean here? Obviously you feel that
'traditional members' are 'blocking' the creation of documentation
somehow. Can you explain more how you perceive this? I am _very_
interested to understand..
>On the one hand, it will be an opportunity to try something new. The people
>involved in the new documentation project will have the freedom to make the
>decisions they want and structure the documentation however they want, right
>from the ground up.
>
>On the other hand, they won't be stepping on anybody's toes. The more
>established members who have been putting countless hours into the project,
>who know this baby almost bit by bit, don't have to worry about things going
>the wrong way because it doesn't _directly_ touch the Cocoon stuff. If later
>they feel that the new doc is working out, then they can think about
>integrating it into the main Cocoon project, but there would be no
>obligation to do so.
>
>
Are you suggesting that you would feel worried about having full commit
access to Cocoon and would prefer to have it on just documentation? Or
are you suggesting that you think 'traditional members' would prefer it
if you had that sort of access?
>But then again, this is a huge project and would require some very dedicated
>people who, as Derek pointed out, have the skill set to accomplish this. I'm
>not sure if these people actually exist...
>
>
I think they do. We've just got to get enough of them together so that
the work isn't too overwhelming.
>Not sure if I'm making myself clear, but I'm interested in hearing others'
>thoughts on this approach.
>
>
I'm very interested in hearing more from your side. I know a lot about
the 'traditional' way of doing things, and obviously, right now, it
isn't working, so we need to do something else.
>In any case, if somebody (Derek??) has the motivation to go ahead and take
>the lead with this, I'd certainly be willing to participate. I've done a few
>documentation projects, so I could help contribute some ideas and direction
>to the process.
>
>
So you don't feel up to taking the lead, but do feel up to helping.
Do others out there feel the same?
Does anyone out there feel able to lead?
I'm __very__ curious.
Also, I hope to be able to assist more with this myself soon.
Regards, Upayavira
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org