You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by David Crossley <cr...@indexgeo.com.au> on 2002/05/15 07:45:04 UTC
[docs] opensource and quality control
The issue of how to introduce at least some minimal
quality control for documentation is creating some friction
on this list. Let us nip it in the bud before it blossoms.
Opensource is all about getting something done and
getting it out so that everyone can build upon it. By the
very nature of opensource, issues will eventually be
addressed.
However, with documentation it is easy to kill a project
if confusing and misguided documents are allowed to
be published.
So, let us develop a procedure whereby the opensource
model is still employed, yet there is initial quality control.
I think that we already have this. It is the duty of the
committer to undertake initial quality control when they
accept the patch from Bugzilla and prepare for their commit.
If they do not know anything about the topic, then they
should not be taking on the patch - let someone else do it.
There will certainly be occasions where a single committer
does not have the expertise to do a review. For these cases
we should have a Draft documentation directory under the
normal src/documentation/xdocs/ (... we already have a
drafts/ directory but it is not linked in). However, for this
to work, we would need to have the website updated far
more often than what currently happens.
After the initial commit, then a notice should be sent to
cocoon-dev to give a chance for review before release.
If there are no comments or fixes, then too bad - it all just
gets released with the authors fixme notes embedded.
The other alternative is to try to set up an area in the
CVS scratchpad to hold any documents with obvious
problems. However, it seems hard to configure the build
procedures for the scratchpad so that "build docs" can
prepare them too. There is a tendency for stuff to languish
in the scratchpad and never see light, so we would
probably just have a different issue. Also, the scratchpad
docs would not get published to the website, so no
opportunity for review by a wider audience.
--David
> Subject: [docs] Draft RMI generator tutorial needs technical review
> Date: Tue, 14 May 2002 08:29:12 -0400
> From: Diana Shannon <te...@mac.com>
>
> Stefano Mazzocchi wrote:
>
> > Ah, one suggestion: don't wait too much for comments.
> > People don't tend to comment *before* things are placed
> > live on the web, but *after*.
>
> What do you mean: that developers are more motivated to fix
> documentation errors once they are public? Or, that advanced,
> motivated users will catch and help fix these problems eventually?
>
> So what do you suggest we do when an author clearly has
> a question or hole? Should that author post a question to
> cocoon-dev, asking for help?
> I'm all for "lowering the bar," but why allow new docs to
> create additional confusion for users when we have the
> talent to eliminate *some* of this up front.
> Remember, it's not code. It doesn't break. New
> and less advanced users give up and go learn Zope...
>
> Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [docs] opensource and quality control
Posted by Ivelin Ivanov <iv...@apache.org>.
I second Bertrand.
Iterative documentation works for other Apache projects as well.
As long as there are inline notes asking for improvement, the doc will
eventually improve.
----- Original Message -----
From: "Bertrand Delacretaz" <bd...@codeconsult.ch>
To: <co...@xml.apache.org>
Sent: Wednesday, May 15, 2002 1:55 AM
Subject: Re: [docs] opensource and quality control
> On Wednesday 15 May 2002 07:45, David Crossley wrote:
> >. . .
> > So, let us develop a procedure whereby the opensource
> > model is still employed, yet there is initial quality control.
> >. . .
>
> Following the opensource model, I think docs should be released as early
as
> possible, with only minimal initial quality control but clearly flagged as
> "draft" or something. AND it must be very easy for all readers to give
their
> feedback on the docs so that they can be improved.
>
> As opposed to code, docs are not easily declared "right" or "wrong", they
can
> start "usable" and become "great" over time I think.
>
> Ideally readers should be able to add their comment directly on the docs
> pages, but as this is not possible today here I suggest the following
> mechanism, which would be easy to implement:
>
> a) each doc has a status attribute: draft, reviewed, reliable, etc.
>
> b) each doc has a unique ID
>
> c) something like this published at the top of each document
(auto-generated
> from the "status" and "doc-id" attributes)
>
> document status:
> draft
> document id:
> 12.452
> confidence level:
> this information has not been verified yet, please comment if you find
> mistakes in it
> send comments/corrections about this document to:
> cocoon-docs@xml.apache.org with "[doc-comments:12.452]" in subject line
>
> (include a "mailto" link for this and a link to a page that explains the
docs
> feedback process)
>
> Provided this is compatible with the current plan for the docs publishing
> mechanism, I'd be willing to implement the necessary changes.
>
> -Bertrand
>
> ---------------------------------------------------------------------
> 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: [docs] opensource and quality control
Posted by Konstantin Piroumian <kp...@apache.org>.
From: "Stefano Mazzocchi" <st...@apache.org>
> Bertrand Delacretaz wrote:
> > On Wednesday 15 May 2002 07:45, David Crossley wrote:
> > >. . .
> > > So, let us develop a procedure whereby the opensource
> > > model is still employed, yet there is initial quality control.
> > >. . .
> >
> > Following the opensource model, I think docs should be released as early
as
> > possible, with only minimal initial quality control but clearly flagged
as
> > "draft" or something. AND it must be very easy for all readers to give
their
> > feedback on the docs so that they can be improved.
>
> Release as early and as often as possible.
>
> Diana, no, people don't go learning PHP because of mistakes in the docs.
> And if they do, great, they had no way to help us anyway so it's not a
> problem if they don't stick around.
>
> I'm not being an asshole, just realistic: I'll tell you a story that
> I've told the students at the University in Milano last week (Nicola and
> Ugo were present).
>
> Perfect stuff doesn't create open source communities: if you take
> something, it works perfectly and doesn't give you any problem, the
> community struggles: there is no refreshing, no new energy coming in.
>
> If there were perfect cocoon docs, you wouldn't even be here. The *same*
> can be said for *every* committer on this list.
...
>
> I won't go as far as suggesting to make mistakes on purpose (I don't do
> that anymore with code myself), but don't bother perceive quality: just
> plant the seed in the right location and water rightly, the plant will
> grow by itself and both you and the plant will be happy.
Can't say that I'm not totally agree with all the above, but one thing I can
say for sure: if Cocoon had perfect docs and were free of minor or major
bugs then I would never ever subscribe to Cocoon Dev list.
--
Konstantin
>
> --
> 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: [docs] opensource and quality control
Posted by Stefano Mazzocchi <st...@apache.org>.
Bertrand Delacretaz wrote:
>
> On Wednesday 15 May 2002 07:45, David Crossley wrote:
> >. . .
> > So, let us develop a procedure whereby the opensource
> > model is still employed, yet there is initial quality control.
> >. . .
>
> Following the opensource model, I think docs should be released as early as
> possible, with only minimal initial quality control but clearly flagged as
> "draft" or something. AND it must be very easy for all readers to give their
> feedback on the docs so that they can be improved.
[skipped]
I totally agree on this vision.
Release as early and as often as possible.
Diana, no, people don't go learning PHP because of mistakes in the docs.
And if they do, great, they had no way to help us anyway so it's not a
problem if they don't stick around.
I'm not being an asshole, just realistic: I'll tell you a story that
I've told the students at the University in Milano last week (Nicola and
Ugo were present).
Perfect stuff doesn't create open source communities: if you take
something, it works perfectly and doesn't give you any problem, the
community struggles: there is no refreshing, no new energy coming in.
If there were perfect cocoon docs, you wouldn't even be here. The *same*
can be said for *every* committer on this list.
Steven told me privately that he considered me a talented person, but
was kind of upset for my attitude of sparking innovation and then step
back... but then I explained the concept of 'software darwinism' and he
understood that my actions were just like a 'spark in the primordial
soup' (his words) [again, no offense for those who don't believe in
this, biological evolution is just used as a metaphore here!]
Now, you guys want more 'early on' quality control, but you *must*
understand that this is against the community dynamics: I mean: it would
be great if somebody would volunteer to perform this every day, but this
is unfeasible, it can't work. It creates bottlenecks, it doesn't humanly
scale and creates frustruation.
On the other hand, if you "let if go", people will find the bugs, the
errors, the mistakes and provide suggestions.
Sure, they will have to spend an extra half an hour against that
eventual error, but gosh, that's always a small price to pay...
... now look at the *real* picture: we are sellfish. We *MUST* be
sellfish, as individuals and as a community. Delegation is
decentralization. And decentralization is the very seed for massive
scalability (as the internet and the web show!)
How do we maximize quality control decentralization? By delegating it to
the user.
Then he has two options:
1) accepting this delegation (and take that half an hour to route
around the problem)
2) rejecting this delegation and walk away to some other technology
Now, there is *NO* way to avoid #2. No matter how perfect your docs are.
On the jserv-dev mail list (the first list I ever partecipated), we had
20 people a day leaving the community, but 21/22 entering. That makes a
400+ people/year community increase. And I'm talking about developers.
They run away? so? who cares. We are all volunteers, this is our energy,
if they don't like it, they go, their choice. And we are both happy,
actually happier if they were somewhat forced to remain.
So, what is our job as developers and community managers? plant seeds,
so that flower blossom, their colors attract new people (but some will
go away anyway), we teach them how to plant new seeds (like I'm doing
right now) and the garden keeps growing.
The intersting thing is that those who left the garden at one point,
might retain a well enough impression to "get back and take a look" at
some point. And at that point, thanks to the new seeds of those who
volunteered to help up planting this garden, they might decide to stay
and help themselves.
And the community, the garden and the fun grows.
But without that half-hour of frustration, it doesn't work, it doesn't
filter them, it doesn't give them itches to scratch, it doesn't give
them challenges to perform, it doesn't give them that extra-will to
penetrate the barrier of blatant use and start getting their hands
dirty.
Sure, commercial companies don't work this way: every new customer is a
good one. But for open source *this* is *NOT* true at all!
I agree on lowering the barrier more and more, but don't try to remove
it, not at all.
I must admit that I used to leave simple bugs *ON PURPOSE* in some
Cocoon code just so that people would find them and I *forced* them to
take a look inside Cocoon, and learn its internals.
A big publisher offered me to write a book on Cocoon on April 2000: my
response was: no way, that would attract too many users and too few
developers.
That early book would have killed my ability to 'raise developers' out
of those users that eventually happened to pass around here. But now
things are different and books are required, and books will appear.
But don't try to give better quality: follow the flow, shape it, don't
save a single user, filter them! Think at a larger scale. Delegation and
decentralization. Otherwise it doesn't work, it can't possibly work on
the longer term.
I know this is a shock for some of you: but I'm pretty sure that those
who are not shocked by this, learned this by themselves and they are
smiling now :)
For docs, just consider this: two more docs are *always* better than
one. No matter what is their quality. And even better: docs that contain
mistakes are actually *better* for this community that those who are
perfect.
I won't go as far as suggesting to make mistakes on purpose (I don't do
that anymore with code myself), but don't bother perceive quality: just
plant the seed in the right location and water rightly, the plant will
grow by itself and both you and the plant will be happy.
--
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: [docs] opensource and quality control
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Wednesday 15 May 2002 12:13, Diana Shannon wrote:
>. . .
> > b) each doc has a unique ID
>
> Do we really need unique ID attribute if filename is unique, or is this
> short-sighted?
>. .
Unique filenames would work for sure, doesn't have to be numerical, just
pratical to include in the subject line tags for comments.
-Bertrand
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [docs] opensource and quality control
Posted by Diana Shannon <te...@mac.com>.
Bertrand Delacretaz wrote:
> On Wednesday 15 May 2002 07:45, David Crossley wrote:
>> . . .
>> So, let us develop a procedure whereby the opensource
>> model is still employed, yet there is initial quality control.
>> . . .
>
> Following the opensource model, I think docs should be released as
> early as
> possible, with only minimal initial quality control but clearly flagged
> as
> "draft" or something. AND it must be very easy for all readers to give
> their
> feedback on the docs so that they can be improved.
I agree with Betrand. I'm starting to appreciate the need to use the
wider community more loosely for CMS roles, not rely on a small group of
overworked committers to provide all QA, even subject matter expertise.
I agree, that if docs are marked draft, etc. we should be able to
release them to the community for comments with the appropriate "use at
your own risk" type disclaimers. I would really be sad if authors spent
a lot of time and effort on a doc was never released because no
committer had the time. I also really hope subject matter experts within
the community would be able to provide feedback on documents as they are
released in this "draft" form. It's a risk, though, if this doesn't
occur.
> As opposed to code, docs are not easily declared "right" or "wrong",
> they can
> start "usable" and become "great" over time I think.
I hope this is possible. This would be wonderful.
> Ideally readers should be able to add their comment directly on the docs
> pages, but as this is not possible today here I suggest the following
> mechanism, which would be easy to implement:
>
> a) each doc has a status attribute: draft, reviewed, reliable, etc.
I have something like this but a bit more elaborate based on the
research I've done on CMS needs.
> b) each doc has a unique ID
Do we really need unique ID attribute if filename is unique, or is this
short-sighted? I know this unique id is used with many database-driven
CMS systems, but I'm questioning if we need this for Cocoon which gives
us so many flexible matching options for requests?
> c) something like this published at the top of each document
> (auto-generated
> from the "status" and "doc-id" attributes)
>
> document status:
> draft
> document id:
> 12.452
> confidence level:
> this information has not been verified yet, please comment if you find
> mistakes in it
> send comments/corrections about this document to:
> cocoon-docs@xml.apache.org with "[doc-comments:12.452]" in subject
> line
Yes! Absolutely. I was planning to add this info at the transformation
stage, especially given the new reality that author contributions may
not be reviewed by cocoon-dev. Perhaps once we agree on dtds, you could
implement this.
> (include a "mailto" link for this and a link to a page that explains
> the docs
> feedback process)
>
> Provided this is compatible with the current plan for the docs
> publishing
> mechanism, I'd be willing to implement the necessary changes.
I understand this discussion should occur on Forrest. Are you subscribed
there? I'll post my current dtds there later today. Feel free to comment
on/expand/revise them. I'm still struggling with how much CMS info
belongs in primarily content docs, how much should remain separate.
Thanks.
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [docs] opensource and quality control
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Wednesday 15 May 2002 11:20, Stephan Michels wrote:
>. . .
> The best way to do this, is to implement the CVS support in cocoon.
>. . .
Yes sure, but there's no such thing today AFAIK - I was trying to suggest a
concrete solution that can be implemented right away.
-Bertrand
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [docs] opensource and quality control
Posted by Sylvain Wallez <sy...@anyware-tech.com>.
Carsten Ziegeler wrote:
>Sylvain Wallez wrote:
>
>
>>What about a 2-sided configuration :
>>- in cocoon.xconf, declare a new source-handler specific to a particular
>>CVS repository
>><source-handler>
>> <protocol name="cocoon-cvs" class="...CVSSourceFactory">
>> <cvsroot>:pserver:****@cvs.apache.org:/home/cvspublic</cvsroot>
>> <password>****</password>
>> <branch>cocoon_2_0_3_branch</branch>
>> </protorol>
>></source-handler>
>>
>>
>>
>Please make a SourceFactory (org.apache.excalibur.source.SourceFactory) out
>of it. With the release 2.1 the source handler is deprecated.
>
>
Sorry Carsten, I'm still talking in old-fashioned 2.0.x terms, as I'm
under a ton of paid work and didn't have time to look at the new source
handling :-/
But I will ;)
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: [docs] opensource and quality control
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Sylvain Wallez wrote:
>
> What about a 2-sided configuration :
> - in cocoon.xconf, declare a new source-handler specific to a particular
> CVS repository
> <source-handler>
> <protocol name="cocoon-cvs" class="...CVSSourceFactory">
> <cvsroot>:pserver:****@cvs.apache.org:/home/cvspublic</cvsroot>
> <password>****</password>
> <branch>cocoon_2_0_3_branch</branch>
> </protorol>
> </source-handler>
>
Please make a SourceFactory (org.apache.excalibur.source.SourceFactory) out
of it. With the release 2.1 the source handler is deprecated.
Carsten
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [docs] opensource and quality control
Posted by Stephan Michels <st...@vern.chem.tu-berlin.de>.
On Wed, 15 May 2002, Sylvain Wallez wrote:
> Diana Shannon wrote:
>
> >
> > On Wednesday, May 15, 2002, at 05:20 AM, Stephan Michels wrote:
> >
> >> The best way to do this, is to implement the CVS support in cocoon.
> >
> >
> > But you still need some form of webapp front-end to address all CMS
> > concerns. CVS versioning is insufficient, IMO.
> >
> >>
> >> I were glad to see a CVSSource and a CVSSourceFactory, but if it too
> >> difficult to map the parameters like revision, cvs repository, and file
> >> into an URI, we could implement this into a generator and transformer?!
> >>
> >> Something like this
> >>
> >> <generator src="src/documentation/xdocs/overview.xml">
> >> <parameter name="cvsroot"
> >> value=":pserver:****@cvs.apache.org:/home/cvspublic"/>
> >> <parameter name="password" value="****"/>
> >> <parameter name="revision" value="1.2"/>
> >> </generator>
> >
>
> What about a 2-sided configuration :
> - in cocoon.xconf, declare a new source-handler specific to a particular
> CVS repository
> <source-handler>
> <protocol name="cocoon-cvs" class="...CVSSourceFactory">
> <cvsroot>:pserver:****@cvs.apache.org:/home/cvspublic</cvsroot>
> <password>****</password>
> <branch>cocoon_2_0_3_branch</branch>
> </protorol>
> </source-handler>
>
> - in the sitemap, use only the path inside the repository, with
> additional optional parameters if a particular version/branch is required
> <map:generate
> src="cocoon-cvs:/src/documentation/xdocs/overview.xml?revision=1.2">
>
> This way, you have a single URL for any file (and revision) in the
> repository, which can be used as a regular Source, or better,
> WriteableSource.
Good Idea! I tested the cvs client from netbeans and the client
from http://javacvs.sourceforge.net/. But both are file based :(
I see no way to get an input stream from a cvs repository.
And the vscgeneric modules from netbeans seems to me also not very
useful for a source handler.
Perhaps anyone know an easy to use libary?!
Stephan Michels.
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [docs] opensource and quality control
Posted by Sylvain Wallez <sy...@anyware-tech.com>.
Diana Shannon wrote:
>
> On Wednesday, May 15, 2002, at 05:20 AM, Stephan Michels wrote:
>
>> The best way to do this, is to implement the CVS support in cocoon.
>
>
> But you still need some form of webapp front-end to address all CMS
> concerns. CVS versioning is insufficient, IMO.
>
>>
>> I were glad to see a CVSSource and a CVSSourceFactory, but if it too
>> difficult to map the parameters like revision, cvs repository, and file
>> into an URI, we could implement this into a generator and transformer?!
>>
>> Something like this
>>
>> <generator src="src/documentation/xdocs/overview.xml">
>> <parameter name="cvsroot"
>> value=":pserver:****@cvs.apache.org:/home/cvspublic"/>
>> <parameter name="password" value="****"/>
>> <parameter name="revision" value="1.2"/>
>> </generator>
>
What about a 2-sided configuration :
- in cocoon.xconf, declare a new source-handler specific to a particular
CVS repository
<source-handler>
<protocol name="cocoon-cvs" class="...CVSSourceFactory">
<cvsroot>:pserver:****@cvs.apache.org:/home/cvspublic</cvsroot>
<password>****</password>
<branch>cocoon_2_0_3_branch</branch>
</protorol>
</source-handler>
- in the sitemap, use only the path inside the repository, with
additional optional parameters if a particular version/branch is required
<map:generate
src="cocoon-cvs:/src/documentation/xdocs/overview.xml?revision=1.2">
This way, you have a single URL for any file (and revision) in the
repository, which can be used as a regular Source, or better,
WriteableSource.
>>
>> And the combination with slash-edit were ultimative ;-)
>
Having a WriteableSource is the key to slash-edit (see
SourceWritingTransformer).
> I agree. The sooner Forrest has a community-based CMS component, the
> better. Just think how wonderful it would be, to build in community
> contributions at the moment software is released (or before). Perhaps
> you might consider joining Forrest to work on building this dream ;).
>
> Diana
Could you elaborate more on how you see such a community CMS ? A big
problem for such a beast is that we currently don't have a servlet
engine running on Apache servers. And even if we had one, having a
webapp allowing to edit the Apache CVS directly from the web leads to
important security issues, and so it would have to be read-only.
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: [docs] opensource and quality control
Posted by Diana Shannon <te...@mac.com>.
On Wednesday, May 15, 2002, at 05:20 AM, Stephan Michels wrote:
> The best way to do this, is to implement the CVS support in cocoon.
But you still need some form of webapp front-end to address all CMS
concerns. CVS versioning is insufficient, IMO.
>
> I were glad to see a CVSSource and a CVSSourceFactory, but if it too
> difficult to map the parameters like revision, cvs repository, and file
> into an URI, we could implement this into a generator and transformer?!
>
> Something like this
>
> <generator src="src/documentation/xdocs/overview.xml">
> <parameter name="cvsroot"
> value=":pserver:****@cvs.apache.org:/home/cvspublic"/>
> <parameter name="password" value="****"/>
> <parameter name="revision" value="1.2"/>
> </generator>
>
> And the combination with slash-edit were ultimative ;-)
I agree. The sooner Forrest has a community-based CMS component, the
better. Just think how wonderful it would be, to build in community
contributions at the moment software is released (or before). Perhaps
you might consider joining Forrest to work on building this dream ;).
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [docs] opensource and quality control
Posted by Stephan Michels <st...@vern.chem.tu-berlin.de>.
On Wed, 15 May 2002, Bertrand Delacretaz wrote:
> On Wednesday 15 May 2002 07:45, David Crossley wrote:
> >. . .
> > So, let us develop a procedure whereby the opensource
> > model is still employed, yet there is initial quality control.
> >. . .
>
> Following the opensource model, I think docs should be released as early as
> possible, with only minimal initial quality control but clearly flagged as
> "draft" or something. AND it must be very easy for all readers to give their
> feedback on the docs so that they can be improved.
The best way to do this, is to implement the CVS support in cocoon.
I were glad to see a CVSSource and a CVSSourceFactory, but if it too
difficult to map the parameters like revision, cvs repository, and file
into an URI, we could implement this into a generator and transformer?!
Something like this
<generator src="src/documentation/xdocs/overview.xml">
<parameter name="cvsroot"
value=":pserver:****@cvs.apache.org:/home/cvspublic"/>
<parameter name="password" value="****"/>
<parameter name="revision" value="1.2"/>
</generator>
And the combination with slash-edit were ultimative ;-)
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [docs] opensource and quality control
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Wednesday 15 May 2002 07:45, David Crossley wrote:
>. . .
> So, let us develop a procedure whereby the opensource
> model is still employed, yet there is initial quality control.
>. . .
Following the opensource model, I think docs should be released as early as
possible, with only minimal initial quality control but clearly flagged as
"draft" or something. AND it must be very easy for all readers to give their
feedback on the docs so that they can be improved.
As opposed to code, docs are not easily declared "right" or "wrong", they can
start "usable" and become "great" over time I think.
Ideally readers should be able to add their comment directly on the docs
pages, but as this is not possible today here I suggest the following
mechanism, which would be easy to implement:
a) each doc has a status attribute: draft, reviewed, reliable, etc.
b) each doc has a unique ID
c) something like this published at the top of each document (auto-generated
from the "status" and "doc-id" attributes)
document status:
draft
document id:
12.452
confidence level:
this information has not been verified yet, please comment if you find
mistakes in it
send comments/corrections about this document to:
cocoon-docs@xml.apache.org with "[doc-comments:12.452]" in subject line
(include a "mailto" link for this and a link to a page that explains the docs
feedback process)
Provided this is compatible with the current plan for the docs publishing
mechanism, I'd be willing to implement the necessary changes.
-Bertrand
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org