Gentoo Archives: gentoo-doc

From: Sven Vermeulen <swift@g.o>
To: gentoo-doc@l.g.o
Subject: Re: [gentoo-doc] [RFC] Marking unmaintained documents
Date: Fri, 09 Sep 2005 19:51:48
In Reply to: [gentoo-doc] [RFC] Marking unmaintained documents by "Jan Kundrát"
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 | Gentoo Documentation Project Lead | Gentoo Council Member The Gentoo Project <<< >>>


Subject Author
Re: [gentoo-doc] [RFC] Marking unmaintained documents "Jan Kundrát" <jkt@g.o>