FDP docs process - round 2

Tue Aug 24 21:53:18 UTC 2004

On Tue, 2004-08-24 at 11:10, Paul W. Frields wrote:
> 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.

Yes.  You can view a tracker bug's dependency tree[1] and see what is
opened, closed, and all sort of states.  That tracker bug can then
roll-up into higher tracker bugs.

Some writers who use bz as a project tool will have a bug for every
chapter, which blocks the bug that is for the whole guide; that whole
guide bug can block a team production bug, which can then roll up into a
QA bug, then a release bug, then closed.

It's simply a dependency tree, and the meaning is in how we assign it.

[1]
https://bugzilla.redhat.com/bugzilla/showdependencytree.cgi?id=129807
> 
> > > 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?

That is a good idea, to have a separate maintenance bug.  Still, since a
bug can block more than one trackers, we might one to have doc tracking
bugs block both Progress and Maintenance -if- the doc is in active
revision.  That might be more rare than I realize ... it's happened to
me with the SELinux FAQ for FC2, there were some significant changes to
sysvinit that happened in a kernel upgrade, which needed to be reflected
in the FAQ.  This is more like using the Progress tracker to keep track
of a doc that is being added to for errata purposes, etc.  It will
likely stay in that Progress location for a shorter amount of time.

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

No, that makes sense. :)

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

+1 :)

- Karsten 
-- 
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41