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: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
