cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@indexgeo.com.au>
Subject Re: Document Gestation Process?
Date Wed, 01 May 2002 07:30:34 GMT
Diana Shannon wrote:
> David Crossley wrote:
> > Diana Shannon wrote:
> >> How will new docs, authored by Cocoon users, come to life?
> >> Here's my current idea, along with some questions.
> >
> > Here is my proposed process. I hope that it helps to arrive
> > at a combined solution.
> 
> Overall, this is a great use of existing resources, something we can 
> quickly implement. I agree with everything, and added only a few 
> comments below.

I did not mean it to automatically replace your suggested
process. I was expecting some merge. If everyone is happy,
then great. Perhaps it is time to get a consensus and start
with some planning docs in CVS.

> We may need to bend this a bit when someone just wants 
> to donate a finished doc, something they wrote for a different purpose 
> (a thesis, presentation, article).

Sure, that is a different process. However, that raises an issue.
The cocoon doco is lean and well-controlled XML. The HTML
rendition is generated for the website with a consistent look-and-feel.
I would not be happy with allowing anything else. No clunky M$Word
docs please.

> Clearly we don't need this for FAQ 
> submissions, do we?

It depends. I see some FAQs that are quite long and involved.
Perhaps bigger issues need a review process.

> > 3. Author consults topic status list (a web page on cocoon web site)
> > to make sure no other draft on this topic is in process. Author sends
> > patch via bugzilla to topic-status.xml to claim the topic.
> Patch should include not only the topic but also the desired doc type, 
> don't you think?
> 
> > 5. Submit patch to Bugzilla to get new outline added to scratchpad.
> > When it is finally into CVS, then send email announcement calling
> > for a "[REVIEW] this-document-name".
> Who sends the email announcement? The author? The committer who adds the 
> patch to the scratchpad? Also, the author needs to subscribe to 
> cocoon-dev.

The Bugzilla reply will go directly to the author when the committer
marks it as Fixed. Perhaps Ken the-automation-expert can build
upon his Patch Summary to send an automatic notification to
the new cocoon-docs list.

> > 8. When author gets the go-ahead, they expand the outline to
> > become the first draft. They send patches via Bugzilla as before
> > and commits still go into CVS scratchpad.
> How long should this take? I hope no too long. Authors won't always be 
> able to wait indefinitely. Some only have small windows of time 
> available for writing because of other work/vacation/other needs.

This is the same situation for everyone. Current committers need
to be attentive. I expect the process to get some people submitting
quality patches and documents. As per normal, that leads to them
being voted in as a new committer. More committers, quicker turnaround.

> > 9. Author reaches a stage where they are happy to have others
> > add input and flesh out any holes. They have flagged any known
> > deficiencies using the <note>FIXME: ... </note> convention. Send
> > announcement to list.
> These notes about holes could appear in outlines. An author shouldn't be 
> discouraged if he/she can't fill in one part of their outline...

Yes.

> > This all hinges on the need to have the Cocoon website updated
> > very often (so as to get the "topic list" out in the open). At the
> > moment the website is just updated after every code release
> > which is not often.
> 
> I agree. Is this a function of someone (who?) simply making more 
> frequent manual updates? What is the current time frame for implementing 
> automated updates?

See Steven/Ken excellent news to forrest-dev.

> As a fallback, we could also post document topic summaries to both lists 
> (as is the case with the patch queue).

This is something that we should set up to happen anyway.

> > One other key point is that there cannot be any single-person
> > bottleneck. Opensource is all about a community working
> > together where no particular person is responsible, yet everyone
> > is responsible.
> 
> Of course. You've eliminated a lot of potential bottlenecks. Great job!
> 
> Diana

I hope so. However, i am still not sure that it is final. I would like
to see more of your quality assurance and review ideas incorporated.
I suppose that we can start small and build more of that in as we go.
--David

---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message