Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cocoon-dev@xml.apache.org
Date: Wed, 1 May 2002 07:34:04 -0400
Subject: Re: Document Gestation Process?
Content-Type: text/plain; charset=US-ASCII; format=flowed
Mime-Version: 1.0 (Apple Message framework v472)
Cc: crossley@indexgeo.com.au
To: cocoon-dev@xml.apache.org
From: Diana Shannon <terracare@mac.com>
In-Reply-To: <02050117175900.03026@igacer>
Message-Id: <57A4A56C-5CF7-11D6-8C35-0030653FE818@mac.com>
Content-Transfer-Encoding: 7bit


On May 1, 2002, David Crossley wrote:

>> 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.

IMHO, our approaches address the same needs.

What's critical to me, *however* it occurs is the sufficient review of 
editors and SMEs during document "incubation" period (outline -> first 
draft). I think such a review will eliminate a great majority of 
documentation problems. My original approach had this process occurring 
off-list because it didn't seem to have a home on any list. For example:
   (1) some expressed very strong feelings about moving the discussion to 
a separate list;
   (2) I thought it would be too much noise for cocoon-dev.

Your approach takes advantage of built-in mechanisms, Bugzilla and cvs, 
to catalyze the document review process. I *really* like that. It makes 
it more institutional/community-oriented, less personal, like some poor 
author/editor pleading for help/attention ;). However, as you say, it 
will only work if people are paying attention. In the same light, moving 
document incubation discussion to a separate list will fail if SMEs 
don't join/participate. If that occurs, then we may need to utilize some 
of my off-list ideas about person-to-person off-list interaction, to 
secure the input we need.

To be honest, I don't see much difference in our approaches. I don't 
think your approach really reduces the number of hoops, just the 
*perception* of those hoops. You approach cleverly and efficiently uses 
existing mechanisms -- not tied to any single person -- so the process 
appears less intimidating, at least for people familiar with the system 
(people on *this* list!). How *new* authors perceive the process will 
vary, but it's really impossible to know this until we start and get 
some feedback from the brave authors who have already volunteered.

> Perhaps it is time to get a consensus and start
> with some planning docs in CVS.

I think it's better to start and adjust as we go. The goal is to develop 
more docs. We can tweak the process as we go, based on how 
efficient/successful the proposed process works. The minute the Cocoon 
web project has dynamic capabilities, some of this will change anyway.

As for planning docs, I have a draft in the form of a to-do list with 
short-, medium-, and long-term goals. I'll be happy to commit it, post 
it to this list, discuss it off-list...


>> 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.

Of course. Still, speaking for myself, I am going to pursue each and 
every document lead that reveals itself. I'll accept any form of 
documentation, and if the author can't participate, I'll be happy to 
convert it to an acceptable form on the author's behalf. IMHO, the 
initial form of a document should not be an obstacle if it's all an 
author is able to contribute.

>
>> 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.

Well, be careful about blurring document distinctions. I still think an 
FAQ should be concise and limited in length. I was proposing separate 
FAQ docs (one doc per FAQ) to address the administrative/patch concerns. 
If more detail is required, an FAQ can serve as a gateway (via links) to 
more appropriate document forms.

If you're interested, read:
    http://www-106.ibm.com/developerworks/library/us-faq/?dwzone=usability

As an aside, thanks to a recent discussion with Nicola Ken on Forrest, 
I'm starting to "see the light" about the utility of topic maps, 
particularly to ensure that authors (who may have a limited view of the 
system) can still participate. But this is way OT for this current 
discussion.

>>
>>> 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.

So to make sure I understand, cocoon-dev and cocoon-docs both receive 
Bugzilla messages? But the discussion only takes place on cocoon-docs?

>>> 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.

Perhaps, but I'm not sure all authors want to be committers. My guess is 
that there's a completely different incentive structure for some. For 
example, I think it's more about having your work published on the 
Cocoon web site than rising through the ranks to achieve commit status 
(i.e. long-term commitment). Or it may be about helping to reduce the 
noise of FAQs on cocoon-users. If Cocoon ends up with its own 
documentation project, then it may be different. I still think expecting 
all authors to generate/submit patches is a lot to expect. I do hope we 
can come up with a better user-interface, given the vast capabilities of 
Cocoon, sooner rather than later.  Look, we're trying to recruit a 
different type of community member, probably one that's less advanced 
than your average developer. I think the sooner Cocoon has a dynamic 
content update system for its docs, via something like slash-edit, the 
better. Perhaps some third-party could host an author's tool, off-site, 
to facilitate the contribution process for potential authors.

>> 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.

I know, but it was my understanding there are administrative 
uncertainties about how/if the automatic update is triggered. If we need 
a manual update, say for a couple of pages, is that something a 
committer can do? Sorry, I just don't know the process.

> 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.

We'll address QA holes as they develop. I'll be keeping a watchful eye.

> I suppose that we can start small and build more of that in as we go.

So, can we work on a draft plan (on or off-list?), and then have a vote? 
I still want to address a few planning issues before voting.

Diana


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