[RFC] Legacy documentation

[Paul W. Frields]

On Wed, 2005-04-06 at 10:21 +0100, Gavin Henry wrote:
> <quote who="Karsten Wade">
> > I've been wondering about this for a while, so when Stuart brought up
> > the age of the Keeping Up to Date tutorial:
> >
> > http://fedora.redhat.com/docs/updates/
> >
> > today on #fedora-docs, I figured it was time to open this discussion.
> > I'm hoping you are interested in taking over some documentation.
> >
> > We have a few documents that are FC2 specific and are going to be
> > orphaned when FC2 moves over to the Legacy Project.  The Docs Project
> > (FDP) follows the Fedora Core release and maintenance schedule, meaning
> > when a version of Core goes to the Legacy Project, the docs should go
> > with it.  I'll list what those docs are (just a few), bring up some
> > ideas about what can be done with them, and finish with a few useful
> > URLs.
> >
> > ## The Docs:
> >
> > We'll have a list that is a bit longer for FC3 when that time comes.
> >
> > Keeping Up to Date (FC2)
> >   http://fedora.redhat.com/docs/updates/
> >   We're likely to update this for FC4, if a writer pops up wanting it.

I mentioned before that I really like Stuart's tutorial so far, and
having spoken up, I'd be willing to take over editorial duties for it,
if there are no objections.

> > Fedora Jargon Buster
> >
> >   http://fedora.redhat.com/docs/jargon-buster/
> >
> >   This was written originally under FC1.  It may not be out of date,
> >   but it hasn't been updated in six months.
> 
> Have you asked the author, mainly Dave?
> 
> >
> > Package List for Fedora Core 2
> >   http://fedora.redhat.com/docs/package-list/fc2/
> >
> >   I don't know anything about this or its value.
> 
> Do people really want to read this doc or just browse the download folder?

Rahul made a good point about this being available elsewhere. There's
also using "yum list" or "up2date --showall | grep <reponame>" to
provide this function, I believe.

[...snip...]
> > ## What to Do?
> >
> > I'm just throwing out a few ideas, which may even be somewhat exclusive
> > of each other.
> >
> > 1. Legacy Docs could be a sub-project of the Docs Project.
> >
> > There is no rule that says what is in our purview.  I keep the nose of
> > the project turned in the direction Fedora Core is going, but the rest
> > of the head can be doing other things at the same time.
> 
> I think they should be maintained if anything is backported, but otherwise
> just freeze them, unless some bugzilla entries come up.

I like this idea best. Karsten makes the observation that any
maintenance will likely be trivial, therefore not a big drag on our
resources -- in fact, much less of a drag, I would think, than teaching
FLP members the docs toolset.

> > Currently, we don't have enough writers to work on new documents that
> > are needed for FC.  I don't know of anyone interested in the Legacy
> > docs.
> 
> Neither do I.
> 
> > IMO, maintenance of a set of Legacy docs is likely to be easier than a
> > doc that tracks something with an active update schedule in FC.  I had
> > this with the SELinux FAQ.  It was very active during the early parts of
> > the release, and tapered off as rawhide become more of the next version.
> >
> > This means that one or two people could maintain quite a large set of
> > docs.  This could be great experience for someone interested in
> > technical writing, open source projects, or need to support a legacy
> > app.
> >
> > By integrating the efforts, current docs could be written with Legacy
> > needs in mind.  Whatever those turn out to be.
> 
> Yes, they can be a basis to work on and update them, rather than starting
> from scratch.

Certainly there would be an obsolescence process to work up -- i.e.
freezing entities, inserting a caveat in the front matter, etc.  We can
work on this as time allows.

> > 2. Legacy Project can form the Legacy Docs as a sub-project.
> >
> > This is more of a throw over the wall scheme.  I'd recommend that the
> > FDP remain available to help train on the tools.
> >
> > Since the Legacy Project is going to need to staff the a documentation
> > effort with writers, you might as well keep them close to the rest of
> > the project.
> 
> Agreed.

The FLP is having enough trouble simply attracting enough community
involvement to keep updates rolling out on a timely basis -- and that is
*not* meant as a slam to anyone involved there.  They are doing good
work, but the project leads have made this observation themselves
continually in their list traffic.  I think dumping (throwing?) docs
work on them is not going to help their cause, and we are already better
equipped to handle a small amount of upkeep work, which is much less
demanding than writing from scratch.  Q.v. above.

> > 3. Legacy Project could cherry-pick from the versioned docs.  The FDP
> > would likely keep the outdated docs available, but mark them clearly as
> > not current.  The FDP will help get Legacy writers up to speed, mainly
> > through our standard docs and procedures, then mailing list support
> > where needed.

See comments to #1 and #2 above.  I think the first option is best.

[...snip...]
> > Thanks - Karsten
> 
> No, thank you.

No no no, thank YOU.  :-D  (food fight ensues)

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20050406/93be52d0/attachment.sig>