[RFC] Legacy documentation

[Paul W. Frields]

On Fri, 2005-04-08 at 10:34 +0100, Stuart Ellis wrote:
> On Tue, 05 Apr 2005 17:49:08 -0700, "Karsten Wade" <kwade at redhat.com>
> said:
> 
> "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."
> 
> Two questions and one suggestion:
> 
> - Do people think it's useful/feasible to specify which versions of
> Fedora a document pertains to within the document, or not ?

Absolutely!  I have used a local entity like &FCLOCALVER; to "fix" the
pertinent information.  This scheme works even for documents that we
will continue to maintain.  If different instructions pertain to FC3
than FC4, for example, because of a radical technology change, we would
probably want to note that in a document.  At some point the author
would likely remove the old instructions, but exactly when is a separate
discussion.  Perhaps the date when the particular version of Core leaves
the support schedule entirely -- i.e. when FLP drops it -- would be a
good target.

> - What should happen when the version of Fedora Core is no longer
> supported by Legacy ?  At some point copies of a document will be still
> in circulation with no support at all.

We'd have to decide whether to keep an "obsolete docs" page around, or
to simply hit 'em with the Official FDP/Acme Death Ray.  I like the
former idea.  I think all documents should include a statement that the
newest official version of a document can be found at the FDP web site.
There could be a statement on the FDP web site to the effect that if you
don't see your document there, check the "obsolete" page for more
information.  That page would include information on when or why a
document was retired, and possibly advice to readers on what to do next
(get a newer FC, check TLDP or other sources, etc.).

> - When a document transfers to Legacy status, it might be worth sticking
> a boiler-plate bit of text at the top, just as we do with draft
> documentation.  Perhaps something like one of these:
> 
> 
> "LEGACY DOCUMENT
> 
> This document relates a version of Fedora Core that is no longer
> supported by the Fedora Project.  Changes in later version of Fedora
> Core may have made the information in this document inaccurate.  Please
> check the Documentation Website at http://fedora.redhat.com/docs/ for a
> current version before carrying out any of the instructions in this
> document on your system.
> 
> This version of the document will not be changed or amended, except to
> correct errors that may result in data loss or a weakening of system
> security.  If you beleive that you have found such an error, please
> report it vis Bugzilla in bug ###."
> 
> "OBSOLETE
> 
> This document relates a version of Fedora Core that is no longer
> supported.  Changes in later version of Fedora Core may have made the
> information presented in this document inaccurate.  Please check the
> Documentation Website at http://fedora.redhat.com/docs/ for a current
> version before carrying out any of the instructions in this document on
> your system.
> 
> No further updates or amendments to this version of the document will be
> made."
> --

These are great suggestions IMHO, and I'd like to see them in Bugzilla
as RFEs.  We can hash out the exact text using the bug.  The common
folder under CVS would be a great place for these!

-- 
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: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20050408/e4f29fc3/attachment.bin