Re: [gentoo-doc] Proposal: remove 'last updated' date from rendered page

[Jan Kundrát]

wireless wrote:
> Well this all depends on your viewpoint. If you want a set of
> documents, that folks with deep gentoo experience can use,
> then stay the coarse. If you (we being the larger gentoo community
> including noobs, novices and nerds) then the last date of
> checking or updating is fundamentally important. We all know the
> internet is full of outdated and erroneous information.

I can't parse the third sentence, sorry. Isn't there missing something 
like "[If you] want us (...) to use it, [then...]"?

> I find Camile's points very consistent with what the average  user or
> noob will need. I would also 'simplify' the process, (see touch below)
> So ask yourself who do the documents need
> to be focused on, the gentoo elite, or the average gentoo
> hack....?

Unlike Josh in his original mail, I'm not proposing removal of any 
information. My reply is related only to the quoted part of cam's mail, 
a periodic update of the date field alone. The reason is that we have 
translators who maintain other languages of the same document, and these 
translators would have to update this "last-modified thing" as well.
We're speaking about roughly ten languages right now. So, basically, 
whenever an English document gets its date updated, you add a task for 
ten people to do. Even though this can be partially automated (like 
"update all non-English documents which were up-to-date before the 
change"), this automation might be misleading to the users, as you'd be 
essentially marking, say, a German document "reviewed", despite that 
you, as the one who touched the English doc, can't even read German and 
therefore have absolutely no idea about correctness of the document 
translation.

In addition, my comment probably makes sense only to the GDP members, as 
"yoswink" is our Spanish lead translator, who would say "I'll cut off 
your finger" whenever we touched the English Handbook.

> It should not be that hard (internally) to track the last date
> the file was  touched using 'touch' or whatever mechanism floats
> your boat, to provide the average user some comfort as to the
> usability, related to the age of the last check for accuracy the
> doc has undergone. If we use the last date the doc was 'touch-ed' be one
> of the gentoo elite, then the mechanism is simple. Surely this sort of
> mechanism would be heralded
> as a gentoo point of excellence among a sea of mediocre distros.

Well, we already do keep track of changes which are "important enough" 
to update the date. We're all fine with this.

> On another note, I think what is needed is something simple and bold
> at the top of the official gentoo docs that clearly let folks know that
> the doc is an official gentoo maintained doc.

Anything at www.gentoo.org/doc/en/ which isn't explicitly marked with a 
disclaimer (like "Disclaimer :  This document is a work in progress and 
should not be considered official yet." or "Disclaimer :  This document 
is not valid and is not maintained anymore.") *is* maintained and is 
supposed to reflect current status of the stable tree. We'd like to 
receive a bugreport for each error you can find. Anything which is found 
elsewhere than at www.gentoo.org might or might not be broken. We can't 
do anything about that, sorry.

> If you google for
> help you get all sorts of gentoo-ish looking docs and the average
> user may not know how to distinguish the official (maintained docs)
> from the rest.  My thoughts here are some sort of 'gentoo-certified'
> symbol that is hyperlinked to a page that delineates (clearly explains)
> the nature of the officially maintained docs. Maybe the
> symbol could be Dali-ish artistic GC for Gentoo Certified.

Er, well, any documentation found anywhere else (like gentoo-wiki.com, 
some blog sites or whatever) will *never* get this "certification" 
anyway. We can't support random stuff on the Internet. Anything what is 
at our webspace is, however, a valid documentation that is supposed to 
be error-free (unless marked with that disclaimer).

You can see samples of these disclaimers at [1] or [2].

Cheers,
-jkt

[1] http://www.gentoo.org/doc/en/ldap-howto.xml
[2] http://www.gentoo.org/doc/en/genkernel.xml

-- 
cd /local/pub && more beer > /dev/mouth