You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Stefano Mazzocchi <st...@apache.org> on 2002/04/16 14:23:14 UTC
[vote] Diana Shannon as Documentation Coordinator
Ladies and Gentlemen,
this is a somewhat atypical request for vote so it requires a deeper and
more detailed explaination.
Cocoon has reached a point where its technical quality has far exceeded
its overall 'usability', in the sense of the ability for users to 'use
the system for their needs'.
Many are expressing their concerns about the fact that Cocoon is a
developer framework, and the road to its use is normally so steep that
very few can manage to get everything out of it.
The best way to lower the gap is to have better docs. Better means:
1) more coherent
2) edited by people that knows the english language (since we use
english as our default natural language) and have editing skills
3) maintained regularly
I've been approached by Diana Shannon who has volunteered to step in and
help with the process of creating a better documentation. She explained
to me her intentions, her skills and her 'devotion to the cocoon cause'
(so to speak :).
I've challenged her offering a 'documentation coordinator' job overhere.
Just like we have a 'release coordinator', I think it makes sense to
have a 'documentation coordinator'.
The job includes:
1) planning and proposing a better (as defined above) documentation
outline
2) coordinating the authoring effort (means: kicking some asses if
people commit code without committing docs that go along with them: we
might go as far as prohibiting code submissions, even in the scratchpad,
without appropriate documentation along)
3) providing editing of existing docs (and future docs)
4) managing relationships between users and developers
I personally think Diana is great for this job becuase:
1) she volunteered (in my book, this would be enough since nobody ever
did in one of my projects after 5 years of more of OSS... but there is
more)
2) her native language is English, but she has worked in many foreign
countries and she speaks several languages.
3) she has a medium understanding of Cocoon as a user. No developer can
have this job since he/she would loose the user's point of view. I think
Diana can be a mix between the two points of view and coordinate them so
that they converge.
All right, at this point I stop and I ask Diana to chime in and present
herself.
Ah, one more thing: she asked me if the community needed samples of her
skills to provide a vote and I admit it's a little strange to ask to
give commit access to somebody without having to do anything.
Well, IMO, volunteering for such a critical yet hard job is enough of a
statement for my vote, so I vote +1 to have Diana 'documentation
coordinator' and grant commit access to her so that she can update the
docs directly.
Of course, we, as a dev community, must make all possible efforts to
help her in those situations where she requires help.
At the end, I'm overly pleased by proposing (finally!) a women in the
Cocoon Development community.
So, Diana, please, introduce yourself and introduce your plan of action
(as you did with me privately) so that the rest of the community can
vote.
Thanks.
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Konstantin Piroumian <kp...@apache.org>.
From: "Stefano Mazzocchi" <st...@apache.org>
> Ladies and Gentlemen,
>
...
>
> I've been approached by Diana Shannon who has volunteered to step in and
> help with the process of creating a better documentation. She explained
> to me her intentions, her skills and her 'devotion to the cocoon cause'
> (so to speak :).
Great!
>
> I've challenged her offering a 'documentation coordinator' job overhere.
> Just like we have a 'release coordinator', I think it makes sense to
> have a 'documentation coordinator'.
Definitely!
>
> The job includes:
>
> 1) planning and proposing a better (as defined above) documentation
> outline
>
> 2) coordinating the authoring effort (means: kicking some asses if
> people commit code without committing docs that go along with them: we
> might go as far as prohibiting code submissions, even in the scratchpad,
> without appropriate documentation along)
Won't a readme.txt be enough for scratchpad? Docs can be written just before
merging with the trunk.
>
> 3) providing editing of existing docs (and future docs)
>
> 4) managing relationships between users and developers
What about the:
5) coordinating samples authoring?
...
> At the end, I'm overly pleased by proposing (finally!) a women in the
> Cocoon Development community.
>
> So, Diana, please, introduce yourself and introduce your plan of action
> (as you did with me privately) so that the rest of the community can
> vote.
+100.
Regards,
Konstantin
>
> Thanks.
>
> --
> Stefano Mazzocchi One must still have chaos in oneself to be
> able to give birth to a dancing star.
> <st...@apache.org> Friedrich Nietzsche
> --------------------------------------------------------------------
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by giacomo <gi...@apache.org>.
On Tue, 16 Apr 2002, Diana Shannon wrote:
>
> Nick Airey wrote:
>
> > I vote for giving her commit access. Anyway, we can always roll back the
> > versions in cvs if something goes too far off the rails. Not that I
> > think it will.
>
> If I were making edits, I'd run them by the original authors for
> comments/criticism before committing. I would also *welcome* any
> technical review of my work prior to commits, particularly for new docs.
> My hope is that there will be multiple iterations of documents, each
> enhanced by feedback from authors, editors, and reviewers.
The true way of making people comment on stuff you've edited/written
etc. is by commiting them into CVS so people on the list
1. have the cvs diff mails to see what you've changed/edited
2. can stand up and do fine work or corrections by iterating over those
docs
As soon as somthing is in CVS it's *ours* and not his or hers or yours
anymore :)
Giacomo
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by David Crossley <cr...@indexgeo.com.au>.
John Morrison wrote:
> Diana Shannon wrote
> > Nick Airey wrote:
> >
> > > I vote for giving her commit access. Anyway, we can always
> > > roll back the
> > > versions in cvs if something goes too far off the rails. Not that
> > > I think it will.
> >
> > If I were making edits, I'd run them by the original authors for
> > comments/criticism before committing. I would also *welcome* any
> > technical review of my work prior to commits,
>
> Commit *then* review - more people can see it. If there's something
> *seriously* wrong, it can always be rolled back ;)
>
> J.
>
> > particularly for new docs.
> > My hope is that there will be multiple iterations of documents, each
> > enhanced by feedback from authors, editors, and reviewers.
> >
> > Diana
A most definite +1 for commit access for Diana. Perhaps this
response to a vote is without precedent - every active committer
has responded, as well as some concerned developers.
It is obviously a hot topic.
Please do not get too concerned about the enormity of
the task, Diana. You are joining an excellent team and
you will not be left on your own. The term "co-ordinator"
does not mean "do all of the work".
I do agree with previous posters - CVS is the way to provide
a "review" process.
--David Crossley
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
RE: [vote] Diana Shannon as Documentation Coordinator
Posted by John Morrison <jo...@ntlworld.com>.
> From: Diana Shannon [mailto:terracare@mac.com]
>
> Nick Airey wrote:
>
> > I vote for giving her commit access. Anyway, we can always roll back the
> > versions in cvs if something goes too far off the rails. Not that I
> > think it will.
>
> If I were making edits, I'd run them by the original authors for
> comments/criticism before committing. I would also *welcome* any
> technical review of my work prior to commits,
Commit *then* review - more people can see it. If there's something
*seriously* wrong, it can always be rolled back ;)
J.
> particularly for new docs.
> My hope is that there will be multiple iterations of documents, each
> enhanced by feedback from authors, editors, and reviewers.
>
> Diana
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Diana Shannon <te...@mac.com>.
Nick Airey wrote:
> I vote for giving her commit access. Anyway, we can always roll back the
> versions in cvs if something goes too far off the rails. Not that I
> think it will.
If I were making edits, I'd run them by the original authors for
comments/criticism before committing. I would also *welcome* any
technical review of my work prior to commits, particularly for new docs.
My hope is that there will be multiple iterations of documents, each
enhanced by feedback from authors, editors, and reviewers.
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Nick Airey <ni...@ihavemoved.com>.
+1 thanks Diana!
> Ah, one more thing: she asked me if the community needed samples of her
> skills to provide a vote and I admit it's a little strange to ask to
> give commit access to somebody without having to do anything.
I vote for giving her commit access. Anyway, we can always roll back the
versions in cvs if something goes too far off the rails. Not that I
think it will.
>
> Well, IMO, volunteering for such a critical yet hard job is enough of a
> statement for my vote, so I vote +1 to have Diana 'documentation
> coordinator' and grant commit access to her so that she can update the
> docs directly.
>
> Of course, we, as a dev community, must make all possible efforts to
> help her in those situations where she requires help.
>
> At the end, I'm overly pleased by proposing (finally!) a women in the
> Cocoon Development community.
>
> So, Diana, please, introduce yourself and introduce your plan of action
> (as you did with me privately) so that the rest of the community can
> vote.
>
> Thanks.
>
> --
> Stefano Mazzocchi One must still have chaos in oneself to be
> able to give birth to a dancing star.
> <st...@apache.org> Friedrich Nietzsche
> --------------------------------------------------------------------
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Ivelin Ivanov <iv...@apache.org>.
+1
I would assume that Diana plans to run a survey for the topics which need to
be documented asap and start with the ones rated highest.
Diana, I would certainly be interested to work with you on some user
documentation for the form handling framework.
Cheers,
Ivelin
----- Original Message -----
From: "Stefano Mazzocchi" <st...@apache.org>
To: "Apache Cocoon" <co...@xml.apache.org>
Sent: Tuesday, April 16, 2002 7:23 AM
Subject: [vote] Diana Shannon as Documentation Coordinator
> Ladies and Gentlemen,
>
> this is a somewhat atypical request for vote so it requires a deeper and
> more detailed explaination.
>
> Cocoon has reached a point where its technical quality has far exceeded
> its overall 'usability', in the sense of the ability for users to 'use
> the system for their needs'.
>
> Many are expressing their concerns about the fact that Cocoon is a
> developer framework, and the road to its use is normally so steep that
> very few can manage to get everything out of it.
>
> The best way to lower the gap is to have better docs. Better means:
>
> 1) more coherent
> 2) edited by people that knows the english language (since we use
> english as our default natural language) and have editing skills
> 3) maintained regularly
>
> I've been approached by Diana Shannon who has volunteered to step in and
> help with the process of creating a better documentation. She explained
> to me her intentions, her skills and her 'devotion to the cocoon cause'
> (so to speak :).
>
> I've challenged her offering a 'documentation coordinator' job overhere.
> Just like we have a 'release coordinator', I think it makes sense to
> have a 'documentation coordinator'.
>
> The job includes:
>
> 1) planning and proposing a better (as defined above) documentation
> outline
>
> 2) coordinating the authoring effort (means: kicking some asses if
> people commit code without committing docs that go along with them: we
> might go as far as prohibiting code submissions, even in the scratchpad,
> without appropriate documentation along)
>
> 3) providing editing of existing docs (and future docs)
>
> 4) managing relationships between users and developers
>
> I personally think Diana is great for this job becuase:
>
> 1) she volunteered (in my book, this would be enough since nobody ever
> did in one of my projects after 5 years of more of OSS... but there is
> more)
>
> 2) her native language is English, but she has worked in many foreign
> countries and she speaks several languages.
>
> 3) she has a medium understanding of Cocoon as a user. No developer can
> have this job since he/she would loose the user's point of view. I think
> Diana can be a mix between the two points of view and coordinate them so
> that they converge.
>
> All right, at this point I stop and I ask Diana to chime in and present
> herself.
>
> Ah, one more thing: she asked me if the community needed samples of her
> skills to provide a vote and I admit it's a little strange to ask to
> give commit access to somebody without having to do anything.
>
> Well, IMO, volunteering for such a critical yet hard job is enough of a
> statement for my vote, so I vote +1 to have Diana 'documentation
> coordinator' and grant commit access to her so that she can update the
> docs directly.
>
> Of course, we, as a dev community, must make all possible efforts to
> help her in those situations where she requires help.
>
> At the end, I'm overly pleased by proposing (finally!) a women in the
> Cocoon Development community.
>
> So, Diana, please, introduce yourself and introduce your plan of action
> (as you did with me privately) so that the rest of the community can
> vote.
>
> Thanks.
>
> --
> Stefano Mazzocchi One must still have chaos in oneself to be
> able to give birth to a dancing star.
> <st...@apache.org> Friedrich Nietzsche
> --------------------------------------------------------------------
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Nicola Ken Barozzi <ni...@apache.org>.
From: "Diana Shannon" <te...@mac.com>
> Sylvain Wallez wrote:
> >
> > Don't forget Vadim, the Lord of Cocoon-users :)
>
> Many users would be entirely lost without Vadim. I still find it hard to
> believe he's a single entity, not an alias for several others! ;)
FYI: http://marc.theaimsgroup.com/?l=xml-cocoon-users&m=101612904325738&w=2
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Diana Shannon <te...@mac.com>.
Sylvain Wallez wrote:
>>
>> 4) managing relationships between users and developers
>>
>
> Don't forget Vadim, the Lord of Cocoon-users :)
Many users would be entirely lost without Vadim. I still find it hard to
believe he's a single entity, not an alias for several others! ;)
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Sylvain Wallez <sy...@anyware-tech.com>.
Stefano Mazzocchi wrote:
>Ladies and Gentlemen,
>
>this is a somewhat atypical request for vote so it requires a deeper and
>more detailed explaination.
>
>Cocoon has reached a point where its technical quality has far exceeded
>its overall 'usability', in the sense of the ability for users to 'use
>the system for their needs'.
>
>Many are expressing their concerns about the fact that Cocoon is a
>developer framework, and the road to its use is normally so steep that
>very few can manage to get everything out of it.
>
>The best way to lower the gap is to have better docs. Better means:
>
> 1) more coherent
> 2) edited by people that knows the english language (since we use
>english as our default natural language) and have editing skills
> 3) maintained regularly
>
>I've been approached by Diana Shannon who has volunteered to step in and
>help with the process of creating a better documentation. She explained
>to me her intentions, her skills and her 'devotion to the cocoon cause'
>(so to speak :).
>
>I've challenged her offering a 'documentation coordinator' job overhere.
>Just like we have a 'release coordinator', I think it makes sense to
>have a 'documentation coordinator'.
>
>The job includes:
>
> 1) planning and proposing a better (as defined above) documentation
>outline
>
That's definitely needed and definitely critical if we want Cocoon to
have a larger audience.
> 2) coordinating the authoring effort (means: kicking some asses if
>people commit code without committing docs that go along with them: we
>might go as far as prohibiting code submissions, even in the scratchpad,
>without appropriate documentation along)
>
That's good also : we often develop some code urged by our own business
needs, and documentation always comes last...
> 3) providing editing of existing docs (and future docs)
>
> 4) managing relationships between users and developers
>
Don't forget Vadim, the Lord of Cocoon-users :)
>I personally think Diana is great for this job becuase:
>
> 1) she volunteered (in my book, this would be enough since nobody ever
>did in one of my projects after 5 years of more of OSS... but there is
>more)
>
She deserves a +1 just for having volunteered !
> 2) her native language is English, but she has worked in many foreign
>countries and she speaks several languages.
>
I personally don't like much writing docs, and having to write them in
english makes me like it even less. I wish I could write something like
Berin's "Cocoon, The Play", but I can't :-/
> 3) she has a medium understanding of Cocoon as a user. No developer can
>have this job since he/she would loose the user's point of view. I think
>Diana can be a mix between the two points of view and coordinate them so
>that they converge.
>
True : it's difficult for a developper to write some entry-level docs
accessible to the beginner.
>All right, at this point I stop and I ask Diana to chime in and present
>herself.
>
I couldn't wait and found at http://terracare.com/company/associates.xml
an intersting bio : what I've seen there makes me confident in Diana's
ability for this job.
>Ah, one more thing: she asked me if the community needed samples of her
>skills to provide a vote and I admit it's a little strange to ask to
>give commit access to somebody without having to do anything.
>
>Well, IMO, volunteering for such a critical yet hard job is enough of a
>statement for my vote, so I vote +1 to have Diana 'documentation
>coordinator' and grant commit access to her so that she can update the
>docs directly.
>
>Of course, we, as a dev community, must make all possible efforts to
>help her in those situations where she requires help.
>
>At the end, I'm overly pleased by proposing (finally!) a women in the
>Cocoon Development community.
>
>So, Diana, please, introduce yourself and introduce your plan of action
>(as you did with me privately) so that the rest of the community can
>vote.
>
Yes, please. But you already have my +1 !
Sylvain
--
Sylvain Wallez
Anyware Technologies Apache Cocoon
http://www.anyware-tech.com mailto:sylvain@apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by David Crossley <cr...@indexgeo.com.au>.
Stefano Mazzocchi wrote:
> Ladies and Gentlemen,
>
> this is a somewhat atypical request for vote so it requires a deeper and
> more detailed explaination.
>
<snip what="job description/>
>
> Well, IMO, volunteering for such a critical yet hard job is enough of a
> statement for my vote, so I vote +1 to have Diana 'documentation
> coordinator' and grant commit access to her so that she can update the
> docs directly.
Well there were lots of +1 votes and plenty of email which
added to the job description. However, i do not remember
seeing Stefano follow up and ask for the account and
commit priveledges to be set up. Or did i miss something?
I am not sure - does it have to be the Vote proposer that
asks root to do it, or can any committer? Diana, is it settled yet?
Also, i presume that Diana would need to be both a Cocoon
and a Forrest committer.
--David Crossley
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Nicola Ken Barozzi <ni...@apache.org>.
From: "Stefano Mazzocchi" <st...@apache.org>
> I've been approached by Diana Shannon who has volunteered to step in and
> help with the process of creating a better documentation. She explained
> to me her intentions, her skills and her 'devotion to the cocoon cause'
> (so to speak :).
>
> I've challenged her offering a 'documentation coordinator' job overhere.
> Just like we have a 'release coordinator', I think it makes sense to
> have a 'documentation coordinator'.
>
> The job includes:
>
> 1) planning and proposing a better (as defined above) documentation
> outline
+1
This would be enoughfor me anyway ;-)
BTW, Diana should have Stefano on her book soon, seeing the massive
documentation he has committed with latest scratchpad stuff! ;-P
Hey, I thought I was the only one that didn't like to write documentation!
;-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Bernhard Huber <be...@a1.net>.
hi,
+1 from me of course
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Andrew Savory <an...@luminas.co.uk>.
On Tue, 16 Apr 2002, Robert Koberg wrote:
> Here is the rub... While i don't think the rock would roll to the bottom
> of the hill to be pushed back up again (perhaps it only rolls half way
> down??). How would Diana manage the authors? I could see it working if
> she could do everything herself but the time necessary for this would be
> more than most people could stand.
I suspect there's lots of people out there willing to help, but
overwhelmed and not sure where to start. Hopefully Dianna will be able to
focus attention and move volunteers in the right direction.
Consider this me foolishly volunteering to help, Diana!
Andrew.
--
Andrew Savory Email: andrew@luminas.co.uk
Managing Director Tel: +44 (0)870 741 6658
Luminas Internet Applications Fax: +44 (0)870 28 47489
This is not an official statement or order. Web: www.luminas.co.uk
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Robert Koberg <ro...@koberg.com>.
Hi!
This is great news. Hopefully Diana will accept! She sounds perfect for
the job and most of the developers so far have seen the need to keep
docs up-to-date.
Christian Haul wrote:
>> 2) coordinating the authoring effort (means: kicking some asses if
>>people commit code without committing docs that go along with them: we
>>might go as far as prohibiting code submissions, even in the scratchpad,
>>without appropriate documentation along)
>>
>
>Err - docs for WIP could end up being Sisiphean...
>
Here is the rub... While i don't think the rock would roll to the bottom
of the hill to be pushed back up again (perhaps it only rolls half way
down??). How would Diana manage the authors? I could see it working if
she could do everything herself but the time necessary for this would be
more than most people could stand.
best,
-Rob
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Jeremy Quinn <je...@media.demon.co.uk>.
At 17:44 +0200 16 04 2002, Christian Haul wrote:
>One thing that bugs me especially is links between docs. Currently
>this is done by pointing to the place the generated HTML will end
>up. Would be great if we could do better (no idea though, XPointer?)
We might try XLink, we could get something like a shared link glossary.
We could write 'arcs' in the documents that reference 'locators' in a
LinkBase, the shared repository of link information; I do this on a couple
of sites with XInclude and XSLT, though you could formailse it and write a
Transformer to do it.
In the documents:
Go to <link xl:to="samples.xmldb"/> and try some out.
or with over-ride:
See this <link xl:to="samples.xmldb">AMAZING</link> stuff!
In the linkbase (authors register their documents' link here):
<loc
xl:label="samples.xmldb"
xl:href="/samples/apps/xmldb/welcome"
xl:title="Samples of Cocoon's XML:DB capabilities">
<name>XML:DB Samples</name>
</loc>
(You need to arrange for the tags to get a few more xlink attributes added
to them, via a DTD etc. specially xl:type="arc|locator|title")
There are different ways of arranging the processing of these documents
together. I have not done one like this before, but I reckon if you wanted
links to work across sub-sitemaps, you would probably want to reference all
loc/@xl:href's from a standard location, like inside the top level sitemap,
then you would have to pass the portion of the url being requested (from
that standard location) to the Xlink XSLT so it could make relative links.
I'm not sure this is possible at the moment.
At <http://www.hrc.wmin.ac.uk/KISS/>, I do it the other way around, I use a
'LinkMap', as the basis for generating the site, where the navigational
hierarchy is defined by a set of nested XLink locators, urls consist
entirely of the XLink label, so there is no mucking about with relative
paths for the browser. But this does not work so well for static rendered
docs ....
regards Jeremy
--
___________________________________________________________________
Jeremy Quinn Karma Divers
webSpace Design
HyperMedia Research Centre
<ma...@mac.com> <http://www.media.demon.co.uk>
<phone:+44.[0].20.7737.6831> <pa...@vizzavi.net>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Christian Haul <ha...@dvs1.informatik.tu-darmstadt.de>.
On 16.Apr.2002 -- 02:23 PM, Stefano Mazzocchi wrote:
> 1) planning and proposing a better (as defined above) documentation
> outline
+1
Esp. having templates and skeletons ("place documentation about XYZ
here") would be great. Although the DTD for xdoc has some comments I
do wonder sometimes about semantics.
One thing that bugs me especially is links between docs. Currently
this is done by pointing to the place the generated HTML will end
up. Would be great if we could do better (no idea though, XPointer?)
> 2) coordinating the authoring effort (means: kicking some asses if
> people commit code without committing docs that go along with them: we
> might go as far as prohibiting code submissions, even in the scratchpad,
> without appropriate documentation along)
Err - docs for WIP could end up being Sisiphean...
> 3) providing editing of existing docs (and future docs)
+10
Chris.
(currently writing docs for database actions...)
--
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
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by David Crossley <cr...@indexgeo.com.au>.
Stefano Mazzocchi wrote:
> Ladies and Gentlemen,
>
> this is a somewhat atypical request for vote so it requires a deeper and
> more detailed explaination.
>
<snip what="job description/>
>
> Well, IMO, volunteering for such a critical yet hard job is enough of a
> statement for my vote, so I vote +1 to have Diana 'documentation
> coordinator' and grant commit access to her so that she can update the
> docs directly.
Well there were lots of +1 votes and plenty of email which
added to the job description. However, i do not remember
seeing Stefano follow up and ask for the account and
commit priveledges to be set up. Or did i miss something?
I am not sure - does it have to be the Vote proposer that
asks root to do it, or can any committer? Diana, is it settled yet?
Also, i presume that Diana would need to be both a Cocoon
and a Forrest committer.
--David Crossley
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by giacomo <gi...@apache.org>.
On Tue, 16 Apr 2002, Diana Shannon wrote:
>
> Giacomo wrote:
>
> >
> >> 8. Develop style guide and author's tips for all future submissions.
> >
> > How does the Forrest project play into this?
>
> I have been lurking on the Forrest list for a while now as well.
>
> By style guide, I am referring to editorial and copy style, not
> presentation style. These are conventions editors follow to achieve a
> consistent form of expression within a set of documents authored by
> different people.
>
> Examples include guidelines like
> 1. One sentence, one idea.
> 2. Active over passive voice.
> 3. Avoid use of colloquialisms (common expressions in English that
> non-native speakers may fail to understand)
> etc.
Ok, good. Thanks for explaining.
Giacomo
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Diana Shannon <te...@mac.com>.
Giacomo wrote:
>
>> 8. Develop style guide and author's tips for all future submissions.
>
> How does the Forrest project play into this?
I have been lurking on the Forrest list for a while now as well.
By style guide, I am referring to editorial and copy style, not
presentation style. These are conventions editors follow to achieve a
consistent form of expression within a set of documents authored by
different people.
Examples include guidelines like
1. One sentence, one idea.
2. Active over passive voice.
3. Avoid use of colloquialisms (common expressions in English that
non-native speakers may fail to understand)
etc.
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by giacomo <gi...@apache.org>.
On Tue, 16 Apr 2002, Diana Shannon wrote:
>
> > So, Diana, please, introduce yourself and introduce your plan of action
> > (as you did with me privately) so that the rest of the community can
> > vote.
>
> I've been happily working with Cocoon (1 and 2) for the past eighteen
> months. My clients and I love it. As a user, however, its frustrating to
> be unable to assist in Cocoon's development because I lack the
> high-order architectural understanding and experience to contribute
> code. So, I decided to ask Stefano if the project could use a little
> editing assistance, to help plug some of the holes many new users seem
> to fall through when they read the documentation.
>
> My background is a mix of programming, design, and educational product
> development. At 39, I'm probably a grandmother compared to the rest of
> you.
Hey, there are some older people like you here, belive me ;)
> I have an engineering degree from Dartmouth College (home of BASIC
> and time-sharing systems). Over the years, I've used lots of different
> programming languages in my work which has focused primarily on
> developing simulation-based training tools. My language of choice over
> the past few years has been Java. I used to provide systems integration
> and consulting services to a number of publishers and presses in the
> States (where I learned/applied all major style/grammar conventions for
> publications). I've also been an author/co-author of a number of
> software- and print-based educational tools, as well as an editor for
> the works for others. So you could say I've experienced first-hand the
> demands and expectations of publishing.
>
> However, I need to make a small disclaimer. I am not a technical
> document editor/writer by training. I have never served, in a formal
> capacity, as a technical document editor/writer. If someone more
> qualified than I would like to step forward to do this job, I would be
> *more* than willing to step back and assist that person. However, I do
> have a strong background and lengthy experience in writing, editing and
> copy editing, particularly with international teams. Please understand
> that I do have tremendous respect for the current Cocoon docs,
> considering the amazing fact that so many authors are writing in a
> non-native language. I have worked in many non-English environments
> myself (primarily Spanish, French, Russian, and a few others), and know
> how difficult that can be (at least for me). My goal, as an
> editor/coordinator, would be simply to increase the efficiency of
> learning efforts for users and to make a stronger impression on some of
> management types who might be evaluating Cocoon.
>
> If I were to do this job, here's how I might begin. Please understand I
> wasn't considering this level of commitment when I initially approached
> Stefano. Therefore, I haven't had a lot of time to prepare my thoughts.
>
> 1. Post a questionnaire to developer and users lists, asking for
> feedback on the shortcomings of existing documentation as well as
> suggestions for new documentation.
Hopefully we get some more precise answers to point us to the
shortcomings than simple stating "Cocoon lacks docs".
> 2. Harvest archives for more feedback on problems/holes/needs. Monitor
> lists for emerging needs, potential contributors, etc.
This is a good point. Usually developers are not very sensible to
monitor questions and fill up the FAQ with it.
> 3. Post to lists a summary of all feedback received.
+1 showing transparency of the coordination work.
> 4. Post to list an outline/action plan/framework proposal to address
> problems. Ask for comments.
> 5. Decide on a plan with a vote.
+1
> 6. Invite contributions of all shapes and sizes from users/developer
> list. Contributions can be rough drafts, outlines, code snippets, etc.
The mailing lists itself contains alot of tips and tricks to be a source
for it but probably you meant this in 1) as well.
> 7. Start editing existing docs. Start authoring new docs.
+1
> 8. Develop style guide and author's tips for all future submissions.
How does the Forrest project play into this?
> 9. Recruit/invite other editors/authors/reviewers to assist with ongoing
> effort
+100
> Down the road, point 9 for me is crucial. I'm probably going to be the
> kind of contributor who can commit in big blocks, not a steady stream. I
> do monitor the lists on a daily basis, though, so this kind of effort
> will complement my existing habits.
Sounds like a good plan to me.
+1
Giacomo
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Davanum Srinivas <di...@yahoo.com>.
+1
-- dims
--- Gianugo Rabellino <gi...@apache.org> wrote:
> Torsten Curdt wrote:
> > <snip/>
> >
> >>Thanks for your consideration. Please let me know if you need any
> >>additional information.
> >
> >
> > nope ;) ...here is my +1
>
> And this is my +1. Together with an offer for help: I was already
> planning something about Cocoon docs, it's really great to have someone
> to lead this effort.
>
> Ciao,
>
> --
> Gianugo Rabellino
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>
=====
Davanum Srinivas - http://xml.apache.org/~dims/
__________________________________________________
Do You Yahoo!?
Yahoo! Tax Center - online filing with TurboTax
http://taxes.yahoo.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Gianugo Rabellino <gi...@apache.org>.
Torsten Curdt wrote:
> <snip/>
>
>>Thanks for your consideration. Please let me know if you need any
>>additional information.
>
>
> nope ;) ...here is my +1
And this is my +1. Together with an offer for help: I was already
planning something about Cocoon docs, it's really great to have someone
to lead this effort.
Ciao,
--
Gianugo Rabellino
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Torsten Curdt <tc...@dff.st>.
<snip/>
> Thanks for your consideration. Please let me know if you need any
> additional information.
nope ;) ...here is my +1
--
Torsten
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Nicola Ken Barozzi <ni...@apache.org>.
From: "Steven Noels" <st...@outerthought.org>
> One of the things we should get started with is to bring the documents
> into sync with the v1.1 xdoc DTD's in Forrest - I'll give them a quick
> look tomorrow and see if they need urgent changes. That way, we are
> Forrest-ready when Forrest is ready :-)
What I've seen is that the basic changes needed are:
- s1|s2|s3|s4 -> section
- change DTD declarations
This was basically all that was needed when I switched the POI project to
the 1.1 DTD (see the new site btw, skin courtesy of the Avalon team, and
they will follow suit shortly).
For the Forrest team: I will commit the new stuff ASAP, hopefully over the
weekend.
Diana, please forrest-dev-subscribe@xml.apache.org , where there is a
project for the new xml.apache.org web site.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Nicola Ken Barozzi <ni...@apache.org>.
From: "Steven Noels" <st...@outerthought.org>
> One of the things we should get started with is to bring the documents
> into sync with the v1.1 xdoc DTD's in Forrest - I'll give them a quick
> look tomorrow and see if they need urgent changes. That way, we are
> Forrest-ready when Forrest is ready :-)
What I've seen is that the basic changes needed are:
- s1|s2|s3|s4 -> section
- change DTD declarations
This was basically all that was needed when I switched the POI project to
the 1.1 DTD (see the new site btw, skin courtesy of the Avalon team, and
they will follow suit shortly).
For the Forrest team: I will commit the new stuff ASAP, hopefully over the
weekend.
Diana, please forrest-dev-subscribe@xml.apache.org , where there is a
project for the new xml.apache.org web site.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
RE: [vote] Diana Shannon as Documentation Coordinator
Posted by Steven Noels <st...@outerthought.org>.
(uh-oh, it seems I was missing out the fun during the past few days)
Diana,
congrats, it seems like you gathered enough votes.
> 9. Recruit/invite other editors/authors/reviewers to assist
> with ongoing
> effort
>
> Down the road, point 9 for me is crucial. I'm probably going
> to be the
> kind of contributor who can commit in big blocks, not a
> steady stream. I
> do monitor the lists on a daily basis, though, so this kind of effort
> will complement my existing habits.
Where can I submit my CV? ;-)
I'm delighted someone will be giving this a headstart before Summer as I
was promising in one of my previous posts.
One of the things we should get started with is to bring the documents
into sync with the v1.1 xdoc DTD's in Forrest - I'll give them a quick
look tomorrow and see if they need urgent changes. That way, we are
Forrest-ready when Forrest is ready :-)
</Steven>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Diana Shannon <te...@mac.com>.
> So, Diana, please, introduce yourself and introduce your plan of action
> (as you did with me privately) so that the rest of the community can
> vote.
I've been happily working with Cocoon (1 and 2) for the past eighteen
months. My clients and I love it. As a user, however, its frustrating to
be unable to assist in Cocoon's development because I lack the
high-order architectural understanding and experience to contribute
code. So, I decided to ask Stefano if the project could use a little
editing assistance, to help plug some of the holes many new users seem
to fall through when they read the documentation.
My background is a mix of programming, design, and educational product
development. At 39, I'm probably a grandmother compared to the rest of
you. I have an engineering degree from Dartmouth College (home of BASIC
and time-sharing systems). Over the years, I've used lots of different
programming languages in my work which has focused primarily on
developing simulation-based training tools. My language of choice over
the past few years has been Java. I used to provide systems integration
and consulting services to a number of publishers and presses in the
States (where I learned/applied all major style/grammar conventions for
publications). I've also been an author/co-author of a number of
software- and print-based educational tools, as well as an editor for
the works for others. So you could say I've experienced first-hand the
demands and expectations of publishing.
However, I need to make a small disclaimer. I am not a technical
document editor/writer by training. I have never served, in a formal
capacity, as a technical document editor/writer. If someone more
qualified than I would like to step forward to do this job, I would be
*more* than willing to step back and assist that person. However, I do
have a strong background and lengthy experience in writing, editing and
copy editing, particularly with international teams. Please understand
that I do have tremendous respect for the current Cocoon docs,
considering the amazing fact that so many authors are writing in a
non-native language. I have worked in many non-English environments
myself (primarily Spanish, French, Russian, and a few others), and know
how difficult that can be (at least for me). My goal, as an
editor/coordinator, would be simply to increase the efficiency of
learning efforts for users and to make a stronger impression on some of
management types who might be evaluating Cocoon.
If I were to do this job, here's how I might begin. Please understand I
wasn't considering this level of commitment when I initially approached
Stefano. Therefore, I haven't had a lot of time to prepare my thoughts.
1. Post a questionnaire to developer and users lists, asking for
feedback on the shortcomings of existing documentation as well as
suggestions for new documentation.
2. Harvest archives for more feedback on problems/holes/needs. Monitor
lists for emerging needs, potential contributors, etc.
3. Post to lists a summary of all feedback received.
4. Post to list an outline/action plan/framework proposal to address
problems. Ask for comments.
5. Decide on a plan with a vote.
6. Invite contributions of all shapes and sizes from users/developer
list. Contributions can be rough drafts, outlines, code snippets, etc.
7. Start editing existing docs. Start authoring new docs.
8. Develop style guide and author's tips for all future submissions.
9. Recruit/invite other editors/authors/reviewers to assist with ongoing
effort
Down the road, point 9 for me is crucial. I'm probably going to be the
kind of contributor who can commit in big blocks, not a steady stream. I
do monitor the lists on a daily basis, though, so this kind of effort
will complement my existing habits.
Thanks for your consideration. Please let me know if you need any
additional information.
Diana Shannon
TerraCare Software
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
RE: [vote] Diana Shannon as Documentation Coordinator
Posted by Vadim Gritsenko <va...@verizon.net>.
> From: Stefano Mazzocchi [mailto:stefano@apache.org]
>
> Ladies and Gentlemen,
>
> this is a somewhat atypical request for vote so it requires a deeper
and
> more detailed explaination.
>
> Cocoon has reached a point where its technical quality has far
exceeded
> its overall 'usability', in the sense of the ability for users to 'use
> the system for their needs'.
>
> Many are expressing their concerns about the fact that Cocoon is a
> developer framework, and the road to its use is normally so steep that
> very few can manage to get everything out of it.
>
> The best way to lower the gap is to have better docs. Better means:
>
> 1) more coherent
> 2) edited by people that knows the english language (since we use
> english as our default natural language) and have editing skills
> 3) maintained regularly
>
> I've been approached by Diana Shannon who has volunteered to step in
and
> help with the process of creating a better documentation. She
explained
> to me her intentions, her skills and her 'devotion to the cocoon
cause'
> (so to speak :).
>
> I've challenged her offering a 'documentation coordinator' job
overhere.
> Just like we have a 'release coordinator', I think it makes sense to
> have a 'documentation coordinator'.
>
> The job includes:
>
> 1) planning and proposing a better (as defined above) documentation
> outline
>
> 2) coordinating the authoring effort (means: kicking some asses if
> people commit code without committing docs that go along with them: we
> might go as far as prohibiting code submissions, even in the
scratchpad,
> without appropriate documentation along)
>
> 3) providing editing of existing docs (and future docs)
>
> 4) managing relationships between users and developers
>
> I personally think Diana is great for this job becuase:
>
> 1) she volunteered (in my book, this would be enough since nobody
ever
> did in one of my projects after 5 years of more of OSS... but there is
> more)
>
> 2) her native language is English, but she has worked in many foreign
> countries and she speaks several languages.
>
> 3) she has a medium understanding of Cocoon as a user. No developer
can
> have this job since he/she would loose the user's point of view. I
think
> Diana can be a mix between the two points of view and coordinate them
so
> that they converge.
>
> All right, at this point I stop and I ask Diana to chime in and
present
> herself.
>
> Ah, one more thing: she asked me if the community needed samples of
her
> skills to provide a vote and I admit it's a little strange to ask to
> give commit access to somebody without having to do anything.
>
> Well, IMO, volunteering for such a critical yet hard job is enough of
a
> statement for my vote, so I vote +1 to have Diana 'documentation
> coordinator' and grant commit access to her so that she can update the
> docs directly.
>
> Of course, we, as a dev community, must make all possible efforts to
> help her in those situations where she requires help.
>
> At the end, I'm overly pleased by proposing (finally!) a women in the
> Cocoon Development community.
>
> So, Diana, please, introduce yourself and introduce your plan of
action
> (as you did with me privately) so that the rest of the community can
> vote.
It's too cool to be true.
+1
Vadim
> Thanks.
>
> --
> Stefano Mazzocchi One must still have chaos in oneself to be
> able to give birth to a dancing star.
> <st...@apache.org> Friedrich Nietzsche
> --------------------------------------------------------------------
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
RE: [vote] Diana Shannon as Documentation Coordinator
Posted by Gerhard Froehlich <g-...@gmx.de>.
+1000
~Gerhard
---------------------------------
Me, Ambivalent? Well, yes and no.
---------------------------------
>-----Original Message-----
>From: Stefano Mazzocchi [mailto:stefano@apache.org]
>Sent: Tuesday, April 16, 2002 2:23 PM
>To: Apache Cocoon
>Subject: [vote] Diana Shannon as Documentation Coordinator
>
>
>Ladies and Gentlemen,
>
>this is a somewhat atypical request for vote so it requires a deeper and
>more detailed explaination.
>
>Cocoon has reached a point where its technical quality has far exceeded
>its overall 'usability', in the sense of the ability for users to 'use
>the system for their needs'.
>
>Many are expressing their concerns about the fact that Cocoon is a
>developer framework, and the road to its use is normally so steep that
>very few can manage to get everything out of it.
>
>The best way to lower the gap is to have better docs. Better means:
>
> 1) more coherent
> 2) edited by people that knows the english language (since we use
>english as our default natural language) and have editing skills
> 3) maintained regularly
>
>I've been approached by Diana Shannon who has volunteered to step in and
>help with the process of creating a better documentation. She explained
>to me her intentions, her skills and her 'devotion to the cocoon cause'
>(so to speak :).
>
>I've challenged her offering a 'documentation coordinator' job overhere.
>Just like we have a 'release coordinator', I think it makes sense to
>have a 'documentation coordinator'.
>
>The job includes:
>
> 1) planning and proposing a better (as defined above) documentation
>outline
>
> 2) coordinating the authoring effort (means: kicking some asses if
>people commit code without committing docs that go along with them: we
>might go as far as prohibiting code submissions, even in the scratchpad,
>without appropriate documentation along)
>
> 3) providing editing of existing docs (and future docs)
>
> 4) managing relationships between users and developers
>
>I personally think Diana is great for this job becuase:
>
> 1) she volunteered (in my book, this would be enough since nobody ever
>did in one of my projects after 5 years of more of OSS... but there is
>more)
>
> 2) her native language is English, but she has worked in many foreign
>countries and she speaks several languages.
>
> 3) she has a medium understanding of Cocoon as a user. No developer can
>have this job since he/she would loose the user's point of view. I think
>Diana can be a mix between the two points of view and coordinate them so
>that they converge.
>
>All right, at this point I stop and I ask Diana to chime in and present
>herself.
>
>Ah, one more thing: she asked me if the community needed samples of her
>skills to provide a vote and I admit it's a little strange to ask to
>give commit access to somebody without having to do anything.
>
>Well, IMO, volunteering for such a critical yet hard job is enough of a
>statement for my vote, so I vote +1 to have Diana 'documentation
>coordinator' and grant commit access to her so that she can update the
>docs directly.
>
>Of course, we, as a dev community, must make all possible efforts to
>help her in those situations where she requires help.
>
>At the end, I'm overly pleased by proposing (finally!) a women in the
>Cocoon Development community.
>
>So, Diana, please, introduce yourself and introduce your plan of action
>(as you did with me privately) so that the rest of the community can
>vote.
>
>Thanks.
>
>--
>Stefano Mazzocchi One must still have chaos in oneself to be
> able to give birth to a dancing star.
><st...@apache.org> Friedrich Nietzsche
>--------------------------------------------------------------------
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
>For additional commands, email: cocoon-dev-help@xml.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Torsten Curdt <tc...@dff.st>.
On Tue, 16 Apr 2002, Stefano Mazzocchi wrote:
<snip/>
> I've challenged her offering a 'documentation coordinator' job overhere.
> Just like we have a 'release coordinator', I think it makes sense to
> have a 'documentation coordinator'.
great!
> The job includes:
>
> 1) planning and proposing a better (as defined above) documentation
> outline
>
> 2) coordinating the authoring effort (means: kicking some asses if
> people commit code without committing docs that go along with them: we
> might go as far as prohibiting code submissions, even in the scratchpad,
> without appropriate documentation along)
ups... we are approaching strict times... ;-)
> 3) providing editing of existing docs (and future docs)
>
> 4) managing relationships between users and developers
>
> I personally think Diana is great for this job becuase:
>
> 1) she volunteered (in my book, this would be enough since nobody ever
> did in one of my projects after 5 years of more of OSS... but there is
> more)
>
> 2) her native language is English, but she has worked in many foreign
> countries and she speaks several languages.
>
> 3) she has a medium understanding of Cocoon as a user. No developer can
> have this job since he/she would loose the user's point of view. I think
> Diana can be a mix between the two points of view and coordinate them so
> that they converge.
>
> All right, at this point I stop and I ask Diana to chime in and present
> herself.
looking forward on that...
> Ah, one more thing: she asked me if the community needed samples of her
> skills to provide a vote and I admit it's a little strange to ask to
> give commit access to somebody without having to do anything.
>
> Well, IMO, volunteering for such a critical yet hard job is enough of a
> statement for my vote, so I vote +1 to have Diana 'documentation
> coordinator' and grant commit access to her so that she can update the
> docs directly.
Well, IMO an introduction would be fine. ...but then - no problem.
> Of course, we, as a dev community, must make all possible efforts to
> help her in those situations where she requires help.
of course...
> At the end, I'm overly pleased by proposing (finally!) a women in the
> Cocoon Development community.
:))
> So, Diana, please, introduce yourself and introduce your plan of action
> (as you did with me privately) so that the rest of the community can
> vote.
..please do so..
cheers
--
Torsten
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by giacomo <gi...@apache.org>.
On Tue, 16 Apr 2002, Stefano Mazzocchi wrote:
> Ladies and Gentlemen,
>
> this is a somewhat atypical request for vote so it requires a deeper and
> more detailed explaination.
>
> Cocoon has reached a point where its technical quality has far exceeded
> its overall 'usability', in the sense of the ability for users to 'use
> the system for their needs'.
>
> Many are expressing their concerns about the fact that Cocoon is a
> developer framework, and the road to its use is normally so steep that
> very few can manage to get everything out of it.
>
> The best way to lower the gap is to have better docs. Better means:
>
> 1) more coherent
> 2) edited by people that knows the english language (since we use
> english as our default natural language) and have editing skills
> 3) maintained regularly
>
> I've been approached by Diana Shannon who has volunteered to step in and
> help with the process of creating a better documentation. She explained
> to me her intentions, her skills and her 'devotion to the cocoon cause'
> (so to speak :).
>
> I've challenged her offering a 'documentation coordinator' job overhere.
> Just like we have a 'release coordinator', I think it makes sense to
> have a 'documentation coordinator'.
+10
>
> The job includes:
>
> 1) planning and proposing a better (as defined above) documentation
> outline
>
> 2) coordinating the authoring effort (means: kicking some asses if
> people commit code without committing docs that go along with them: we
> might go as far as prohibiting code submissions, even in the scratchpad,
> without appropriate documentation along)
>
> 3) providing editing of existing docs (and future docs)
>
> 4) managing relationships between users and developers
>
> I personally think Diana is great for this job becuase:
>
> 1) she volunteered (in my book, this would be enough since nobody ever
> did in one of my projects after 5 years of more of OSS... but there is
> more)
>
> 2) her native language is English, but she has worked in many foreign
> countries and she speaks several languages.
>
> 3) she has a medium understanding of Cocoon as a user. No developer can
> have this job since he/she would loose the user's point of view. I think
> Diana can be a mix between the two points of view and coordinate them so
> that they converge.
That's a great plus. I know that by experience :)
> All right, at this point I stop and I ask Diana to chime in and present
> herself.
Yes, please, Diana.
> Ah, one more thing: she asked me if the community needed samples of her
> skills to provide a vote and I admit it's a little strange to ask to
> give commit access to somebody without having to do anything.
>
> Well, IMO, volunteering for such a critical yet hard job is enough of a
> statement for my vote, so I vote +1 to have Diana 'documentation
> coordinator' and grant commit access to her so that she can update the
> docs directly.
You get my +1, too.
> Of course, we, as a dev community, must make all possible efforts to
> help her in those situations where she requires help.
>
> At the end, I'm overly pleased by proposing (finally!) a women in the
> Cocoon Development community.
This is a big enrichment.
Giacomo
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Stefano Mazzocchi <st...@apache.org>.
Nicola Ken Barozzi wrote:
> Stefano, can you help us?
No, sorry, I can't dedicate any resource to this ATM and I'm not
currently in a mood where fighting political battles can be useful to
anyone. :(
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
DTD updates (was Re: [vote] Diana Shannon as Documentation Coordinator)
Posted by Nicola Ken Barozzi <ni...@apache.org>.
From: "Steven Noels" <st...@outerthought.org>
> Nicola wrote:
>
> > > Does anyone has strong feelings on the title-attribute for
> > > section elements?
>
> > - attributes take up less space that tags, so are preferred
> > (sizewise) with
> > short and frequent infos
<section title="foo">
21 bytes
<section>
<title>foo</title>
<section>
36 bytes
The difference in percentage gets lower if "foo" is a large string.
The difference in percentage gets higher if the title is usef frequently.
> > - that tags are bettar at keeping data while tags at metadata.
> > - the DTD you usually use is better than the new one ;-)
> > - usual dire straits user: "I want my DTD!" ;-)
>
> OK, seems like: don't fix what isn't broken (yet ;-)
That's why I kept the book.xml: we have to help projects use the new DTD.
The more we change, the more difficult acceptance will be and the more
difficult is our job in transforming old DTD docs to the new one.
For example, the Avalon guys are interested in Forrest but they want to keep
1.0 DTD for now.
I'm confident that they will change over time, but we need to support them
in the time being.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
RE: [vote] Diana Shannon as Documentation Coordinator
Posted by Steven Noels <st...@outerthought.org>.
Nicola wrote:
> > Does anyone has strong feelings on the title-attribute for
> > section elements?
> - attributes take up less space that tags, so are preferred
> (sizewise) with
> short and frequent infos
??
> - that tags are bettar at keeping data while tags at metadata.
> - the DTD you usually use is better than the new one ;-)
> - usual dire straits user: "I want my DTD!" ;-)
OK, seems like: don't fix what isn't broken (yet ;-)
I'll hold my horses. A title attribute it will be (except if some more
people re voicing their opinion).
</Steven>
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Nicola Ken Barozzi <ni...@apache.org>.
From: "Steven Noels" <st...@outerthought.org>
> Does anyone has strong feelings on the title-attribute for
> section elements?
A bit generic as a question ;-P
No I don't have *any* strong feelings on DTDs, as long as the semantical
bits are there in a way or the other.
My generic DTD 2cents:
- attributes take up less space that tags, so are preferred (sizewise) with
short and frequent infos
- that tags are bettar at keeping data while tags at metadata.
- the DTD you usually use is better than the new one ;-)
- usual dire straits user: "I want my DTD!" ;-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
RE: [vote] Diana Shannon as Documentation Coordinator
Posted by Steven Noels <st...@outerthought.org>.
> The only thing that stops us in doing this for other projects
> is where-how
> to set this up at Apache.
>
> I'm CC to the forrest list.
>
> Guys, how can we set up a machine to make Forrest run automatically?
>
> Stefan already has done a <deliver> tag for Gump to make this
> possible, but
> Sam is holding it for security reasons.
> Originally I thought that we could use Gump runs to make this
> happen, but
> the projects have very different time constraints; Forrest
> must run with a
> much higher availability.
>
> Stefano, can you help us?
I also polled Sam, no reaction :-|
For daily runs, I guess I could set up a cron job on our machine (which
is up most of the time, but don't expect 7x7 24/24) - but I could use
some help with that.
As far as the new xml.apache.group look&feel is concerned, I'll hop in
finishing off what I have done so far when you committed your patches.
As I said in private to Dianna, I'll double-check DTD's before the end
of this week. Does anyone has strong feelings on the title-attribute for
section elements?
</Steven>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
RE: [vote] Diana Shannon as Documentation Coordinator
Posted by Steven Noels <st...@outerthought.org>.
> The only thing that stops us in doing this for other projects
> is where-how
> to set this up at Apache.
>
> I'm CC to the forrest list.
>
> Guys, how can we set up a machine to make Forrest run automatically?
>
> Stefan already has done a <deliver> tag for Gump to make this
> possible, but
> Sam is holding it for security reasons.
> Originally I thought that we could use Gump runs to make this
> happen, but
> the projects have very different time constraints; Forrest
> must run with a
> much higher availability.
>
> Stefano, can you help us?
I also polled Sam, no reaction :-|
For daily runs, I guess I could set up a cron job on our machine (which
is up most of the time, but don't expect 7x7 24/24) - but I could use
some help with that.
As far as the new xml.apache.group look&feel is concerned, I'll hop in
finishing off what I have done so far when you committed your patches.
As I said in private to Dianna, I'll double-check DTD's before the end
of this week. Does anyone has strong feelings on the title-attribute for
section elements?
</Steven>
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Nicola Ken Barozzi <ni...@apache.org>.
From: "Carsten Ziegeler" <cz...@s-und-n.de>
>
> Nicola Ken Barozzi wrote:
> >
> >
> > From: "Carsten Ziegeler" <cz...@s-und-n.de>
> >
> > > Definitly a big +1 for having a 'documentation coordinator' and
> > > another +1 for you Diana doing this job.
> > >
> > > I would like to add another important point to the "job description":
> > >
> > > * Updating the Cocoon Web Site (= deploying new documentation).
> >
> > It will be automatic soon, so no need to deploy by hand.
> >
> Don't get me wrong, but *when* is "soon"?
The POI project is already using a local copy of Forrest to have their site
updated every 2 hours since yesterday.
Andy uses his server for it.
The only thing that stops us in doing this for other projects is where-how
to set this up at Apache.
I'm CC to the forrest list.
Guys, how can we set up a machine to make Forrest run automatically?
Stefan already has done a <deliver> tag for Gump to make this possible, but
Sam is holding it for security reasons.
Originally I thought that we could use Gump runs to make this happen, but
the projects have very different time constraints; Forrest must run with a
much higher availability.
Stefano, can you help us?
(NOTE: I'm committing new stuff on Forrest today, to the latest updated I
did related to the POI and Avalon docs)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Nicola Ken Barozzi <ni...@apache.org>.
From: "Carsten Ziegeler" <cz...@s-und-n.de>
>
> Nicola Ken Barozzi wrote:
> >
> >
> > From: "Carsten Ziegeler" <cz...@s-und-n.de>
> >
> > > Definitly a big +1 for having a 'documentation coordinator' and
> > > another +1 for you Diana doing this job.
> > >
> > > I would like to add another important point to the "job description":
> > >
> > > * Updating the Cocoon Web Site (= deploying new documentation).
> >
> > It will be automatic soon, so no need to deploy by hand.
> >
> Don't get me wrong, but *when* is "soon"?
The POI project is already using a local copy of Forrest to have their site
updated every 2 hours since yesterday.
Andy uses his server for it.
The only thing that stops us in doing this for other projects is where-how
to set this up at Apache.
I'm CC to the forrest list.
Guys, how can we set up a machine to make Forrest run automatically?
Stefan already has done a <deliver> tag for Gump to make this possible, but
Sam is holding it for security reasons.
Originally I thought that we could use Gump runs to make this happen, but
the projects have very different time constraints; Forrest must run with a
much higher availability.
Stefano, can you help us?
(NOTE: I'm committing new stuff on Forrest today, to the latest updated I
did related to the POI and Avalon docs)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
RE: [vote] Diana Shannon as Documentation Coordinator
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Nicola Ken Barozzi wrote:
>
>
> From: "Carsten Ziegeler" <cz...@s-und-n.de>
>
> > Definitly a big +1 for having a 'documentation coordinator' and
> > another +1 for you Diana doing this job.
> >
> > I would like to add another important point to the "job description":
> >
> > * Updating the Cocoon Web Site (= deploying new documentation).
>
> It will be automatic soon, so no need to deploy by hand.
>
Don't get me wrong, but *when* is "soon"?
Carsten
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [vote] Diana Shannon as Documentation Coordinator
Posted by Nicola Ken Barozzi <ni...@apache.org>.
From: "Carsten Ziegeler" <cz...@s-und-n.de>
> Definitly a big +1 for having a 'documentation coordinator' and
> another +1 for you Diana doing this job.
>
> I would like to add another important point to the "job description":
>
> * Updating the Cocoon Web Site (= deploying new documentation).
It will be automatic soon, so no need to deploy by hand.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
RE: [vote] Diana Shannon as Documentation Coordinator
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Definitly a big +1 for having a 'documentation coordinator' and
another +1 for you Diana doing this job.
I would like to add another important point to the "job description":
* Updating the Cocoon Web Site (= deploying new documentation).
Cheers
Carsten
Stefano Mazzocchi wrote:
>
> Ladies and Gentlemen,
>
> this is a somewhat atypical request for vote so it requires a deeper and
> more detailed explaination.
>
> Cocoon has reached a point where its technical quality has far exceeded
> its overall 'usability', in the sense of the ability for users to 'use
> the system for their needs'.
>
> Many are expressing their concerns about the fact that Cocoon is a
> developer framework, and the road to its use is normally so steep that
> very few can manage to get everything out of it.
>
> The best way to lower the gap is to have better docs. Better means:
>
> 1) more coherent
> 2) edited by people that knows the english language (since we use
> english as our default natural language) and have editing skills
> 3) maintained regularly
>
> I've been approached by Diana Shannon who has volunteered to step in and
> help with the process of creating a better documentation. She explained
> to me her intentions, her skills and her 'devotion to the cocoon cause'
> (so to speak :).
>
> I've challenged her offering a 'documentation coordinator' job overhere.
> Just like we have a 'release coordinator', I think it makes sense to
> have a 'documentation coordinator'.
>
> The job includes:
>
> 1) planning and proposing a better (as defined above) documentation
> outline
>
> 2) coordinating the authoring effort (means: kicking some asses if
> people commit code without committing docs that go along with them: we
> might go as far as prohibiting code submissions, even in the scratchpad,
> without appropriate documentation along)
>
> 3) providing editing of existing docs (and future docs)
>
> 4) managing relationships between users and developers
>
> I personally think Diana is great for this job becuase:
>
> 1) she volunteered (in my book, this would be enough since nobody ever
> did in one of my projects after 5 years of more of OSS... but there is
> more)
>
> 2) her native language is English, but she has worked in many foreign
> countries and she speaks several languages.
>
> 3) she has a medium understanding of Cocoon as a user. No developer can
> have this job since he/she would loose the user's point of view. I think
> Diana can be a mix between the two points of view and coordinate them so
> that they converge.
>
> All right, at this point I stop and I ask Diana to chime in and present
> herself.
>
> Ah, one more thing: she asked me if the community needed samples of her
> skills to provide a vote and I admit it's a little strange to ask to
> give commit access to somebody without having to do anything.
>
> Well, IMO, volunteering for such a critical yet hard job is enough of a
> statement for my vote, so I vote +1 to have Diana 'documentation
> coordinator' and grant commit access to her so that she can update the
> docs directly.
>
> Of course, we, as a dev community, must make all possible efforts to
> help her in those situations where she requires help.
>
> At the end, I'm overly pleased by proposing (finally!) a women in the
> Cocoon Development community.
>
> So, Diana, please, introduce yourself and introduce your plan of action
> (as you did with me privately) so that the rest of the community can
> vote.
>
> Thanks.
>
> --
> Stefano Mazzocchi One must still have chaos in oneself to be
> able to give birth to a dancing star.
> <st...@apache.org> Friedrich Nietzsche
> --------------------------------------------------------------------
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org