Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Sven Vermeulen]

On Thu, Sep 08, 2005 at 06:56:26PM +0200, Jan Kundrát wrote:
> Currently we have quite a lot of "unsupported"/"invalid"/"unmaintained"
> documents for one of these reasons:
>
> a) Third party article

We "can" fix those, but you don't see any news site "fix" their news items
after a year... they are kept online as a reference. You might want to write
a new article about the same subject but more accurate - having the old
article at your disposal can be very interesting.

> b) Older Handbook

Although I can see why you want the chapters of the older handbooks "marked"
as out-dated, some people still use the older handbooks, especially if they
have older release media and want a networkless installation.

But then again, that's not the point :) Personally, I don't think we need
anything red on those handbooks - I would refer to the people's common sense
when they are reading the 2004.3 handbook :)

> c) Translation in language which is not officially supported

We don't link that language; the documents are made available if you know
the URI (which is of course not difficult to grasp). Perhaps we can disable
viewing it entirely unless some variable is set (?override=1) but I don't
think we should.

Each document on our web site is "official" in the sense that either we or a
different Gentoo project is in charge of it. For our documents, this means
that users can post bugreports on the document if they want or even send us
fixes.

With this in mind, having the outdated documents online keeps the bug report
flow coming in - which is a good thing. It has happened in the past that a
guide that was once unmaintained and outdated got updated and is now
accurate and a pleasure to read.

Yes, I know you want something to tell the users "Beware, this document
might contain wrong information" but then again, how would you know the
document gives wrong directives to the user? An old hardware-related guide
might still be perfectly valid - just not updated. Or a very recent guide
can contain erroneous commands while it is still actively maintained.

Imo, as long as there is no AI that can inform us about the malicious
content of a document, we can't easily mark such documents as "outdated" or
"erroneous". I have made a small attempt by allowing us to mark a specific
bug as a showstopper in metadoc - as a result, the document will be unlinked
from the index page. This can be extended by adding-in a <warn> on top of
the document, but you'll have to fight Xavier with this as this results in
another few queries of metadoc and such and makes the XSL again more
obscure.

Wkr,
      Sven Vermeulen




-- 
  Gentoo Foundation Trustee          |  http://foundation.gentoo.org
  Gentoo Documentation Project Lead  |  http://www.gentoo.org/proj/en/gdp
  Gentoo Council Member  

  The Gentoo Project   <<< http://www.gentoo.org >>>