FDP docs process - round 2

[Paul W. Frields]

On Tue, 2004-08-24 at 13:08, Dave Pawson wrote:
> On Mon, 2004-08-23 at 21:59, Karsten Wade wrote:
> > I think there's a step/process missing in the middle there.  I just
> > encountered having two active versions of the "same" document and need
> > another doc-bug for it.  I got to thinking about how this could be
> > handled in the process, and so am proposing a solution, presented as a
> > *new* lifecycle for a document, DocA:
> > 
> > 1. Open BugA1 for DocA while you are writing it, assigned to the
> > in-progress doc tracker bug, TrackProgress.  BugA1 is the bug you pass
> > to editors, QA and release, etc. as defined in the process.
> > 
> > 2. When ready to post, reassign BugA1 to TrackRelease, the release
> > tracking bug.
> 
> Which makes one 'name' align with two items? 

I'm not sure, but I don't think that's correct. BugA1 is a single bug at
this point, say for "mirror-tutorial". While I'm writing it, it's in
progress and blocks the Progress tracker bug. Once it's edited and
"camera-ready" (for release on &FDPDOCS-URL; along with everything else
ready for a release), we remove it from blocking Progress and add it to
blocking Release. The blocking essentially serves as a "checklist" for a
bunch of other bugs for a variety of purposes, if I've been thinking
about it correctly up until now.

> > 3. When DocA is released against a version of Fedora, the associated
> > BugA1 is sent back to TrackProgress.  It remains in TrackProgress while
> > it is being maintained.
> And its purpose is...
> 
>    Sounds like the sort of 'what if' guessing that occurs?

Not at all. When my "mirror-tutorial" has been checked against the
current release (let's say FC3, and let's also say in October), and a
bunch of docs are "released" by FDP onto the site for user reference, we
need some way of showing that those docs are now on a checklist for
maintenance. It might also be used for determining obsolescence, or any
number of other purposes.

One point for Karsten to consider: At the point that release happens,
would it be more helpful to have, for example, a FC3DocMaintenance
tracker bug? Otherwise our "Progress" tracker begins to get a little
muddy in my mind. Not that we should set *that* as a limiting factor,
mind you. ;-)  In other words, does it get confusing what the "Progress"
tracker is for at that point, with some documents that might be a little
longer in the growth stage?

> > 4. At some point, Fedora releases a new version, and DocA is going to be
> > branched for the new version into DocA1.  At this point, BugA2 is opened
> > for DocA2, the new version.  BugA2 and BugA1 can now work in parallel,
> > each pointing at a specific version of a doc in CVS.

Karsten, if I can reply at this point in the thread: To me this is not
confusing if the existing bug blocks "FC3DocMaintenance," and a new bug
opens for "Progress." Am I reading this right? If I'm hopelessly lost
here, I'd appreciate more explanation when you have time, since I am not
old hat at Bugzilla usage, other than the odd bug that I've entered and
looked in on from time to time.

> Suggest a KISS principle is far more appropriate.
> If it happens, deal with it.

I couldn't disagree more with the second sentence. That's a recipe for
disaster in a distributed project like this. As for the first, well, as
long as we can have the process clearly written down somewhere in a
recipe format, then I don't see how it could get much easier.
Contributors *will* have to follow some logical rules in order for this
to work, otherwise it's the wild wild west.

Remember that not every contributor has to do this stuff, but *someone*
has to for the process to work, and in a lot of cases that will be the
person who is responsible for maintenance of a document. If the
responsibility isn't designated ahead of time, it's very easy for the
FDP to become a dumping ground for documentation that becomes as useless
or outdated as much of the stuff you find by just doing Google searches.

> > Pluses? Minuses?  I'll fix this into the XML process doc if it makes
> > sense.
> 
> Not to me Karsten. Sounds like ISO9000 on steroids. Processes for the
> sake of it? 

I don't see that, sorry. Personally, I am already finding Bugzilla an
indispensable aid as a TODO I sit down to work on this project. That
wouldn't be the case if Karsten hadn't delineated some process steps to
begin with. I think the new ones sound pretty logical, with the possible
exceptions above. (Those may simply be a matter of my not understanding
the concept, we'll see.)

-- 
Paul W. Frields, RHCE