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

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

[Josh Saddler]

[-- Attachment #1: Type: text/plain, Size: 1093 bytes --]

Hi guys. I dunno about you, but I'm getting tired of folks bashing our 
docs as being "out of date", "stale", "old", or "inaccurate" just 
because of the displayed date of the last update.

I propose that we keep the date inside the document code, for our own 
internal purposes, but remove it from the final rendered page.

As you know, the date displayed has little relevance to when we last 
actually touched-up the document, given our internal date bump policy.

The only possible downside I can see to this is that we might get fewer 
patches/bug reports from users who see an "old" date and feel the need 
to send in stuff based on it. Anyone know if this is a common 
occurrence? Is there otherwise really a *need* to display the date?

I look at it like this . . . sometimes, our docs are okay because 
they're feature-complete. They don't *need* any further updating. Just 
like gamin, which hasn't had an upstream release since 2007....it's 
because it "just works." I like to think our docs are this way, too. 
Mostly. :)

So. There's my proposal. Thoughts?


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

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

[Camille Huot]

On 9/3/08, Josh Saddler <nightmorph@gentoo.org> wrote:
> I'm getting tired of folks bashing our docs
> as being "out of date", "stale", "old", or "inaccurate" just because of the
> displayed date of the last update.

What's the point saying a doc is out of date if they haven't any issue
with it? -- they can't have any, since the doc is up to date ;)

> The only possible downside I can see to this is that we might get fewer
> patches/bug reports from users who see an "old" date and feel the need to
> send in stuff based on it. Anyone know if this is a common occurrence? Is
> there otherwise really a *need* to display the date?

I think this would be a bad motivation to remove the last updated
information. The date show us if a doc has been updated recently or
not, and it's a valuable information even if there is nothing to
update. It represents the date of the information we put into the doc.
If you remove the date, you can't distinguish two versions of a (HTML)
document anymore. How to tell if this is the last version or a cached
one?

> I look at it like this . . . sometimes, our docs are okay because they're
> feature-complete. They don't *need* any further updating. Just like gamin,
> which hasn't had an upstream release since 2007....it's because it "just
> works." I like to think our docs are this way, too. Mostly. :)

As a workaround, I would suggest to bump the date when an old document
has been checked, tested and certified with current material.

Best regards,
-- 
Camille Huot

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

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 281 bytes --]

Camille Huot wrote:
> As a workaround, I would suggest to bump the date when an old document
> has been checked, tested and certified with current material.

If I were yoswink, I'd kill you for such a change.

Cheers,
-jkt

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

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

[Niklas Johansson]

Maybe it is possible to implement some sort of "up-to-date-system". A
lot of pages on the internet have the question "was this helpful?",
maybe if a lot of people find the page helpful the date can be updated
to signal that the page is "fresh", working and useful.

On Wed, Sep 3, 2008 at 4:44 PM, Jan Kundrát <jkt@gentoo.org> wrote:
> Camille Huot wrote:
>>
>> As a workaround, I would suggest to bump the date when an old document
>> has been checked, tested and certified with current material.
>
> If I were yoswink, I'd kill you for such a change.
>
> Cheers,
> -jkt
>
> --
> cd /local/pub && more beer > /dev/mouth
>
>

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

[wireless]

Jan Kundrát wrote:
> Camille Huot wrote:
>> As a workaround, I would suggest to bump the date when an old document
>> has been checked, tested and certified with current material.

> If I were yoswink, I'd kill you for such a change.


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 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....?


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.

I would suggest keeping the mechanism for updating the date, simple
as in the use of 'touch' or such simple means. If you make it
elaborate and complex, then it will be a nightmare. Not changing
the date, except for a blue moon occurrence, instills doubt
and those confused do not posses the skills of accurate document
differentiation. If they did, they  would not need the document
to resolve their ignorance of the particular issue which they
seek help, guidance or just a cookbook set of command examples.


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. 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.


just random thoughts, nothing that should incite folks to anger
(hopefully)


James

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

[Sven Vermeulen]

On Wed, Sep 3, 2008 at 4:44 PM, Jan Kundrát <jkt@gentoo.org> wrote:
> Camille Huot wrote:
>>
>> As a workaround, I would suggest to bump the date when an old document
>> has been checked, tested and certified with current material.
>
> If I were yoswink, I'd kill you for such a change.

OMG they killed Cam !!

And, to be on-topic: I'd rather keep the current system. Using a
"touch" way is imo pointless and more prone to issues (for instance,
fix a language typo on an outdated document shouldn't bump the date
nor version as the document is still outdated).

Removing the date will silence people who say documents are outdated
(when they are not) but will probably create voices that would like to
see a "last modified" date.

In my opinion, documents should always have a "last modified" date. If
you want some sort of document lifecycle, you might want to introduce
a revision period (for instance, every vital doc should be revised
every 3 months, every other doc every year) and add in two headers:
"last revision" and "next revision date"...

Or something completely different :-)

Wkr,
  Sven Vermeulen

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

[Camille Huot]

On 9/3/08, wireless <wireless@tampabay.rr.com> wrote:
> 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.

Tracking whatever we want to track is not a problem. The question is
do we want to track a revision date?

And touch isn't the right way to do it :)

> 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.

In fact, if I understand correctly the terms of use of the Gentoo name
and logo (http://www.gentoo.org/main/en/name-logo.xml), such sites (if
not illegal by using gentoo in their domainname) HAVE to state
explicitly that they're not official Gentoo.

-- 
Camille Huot

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

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 4340 bytes --]

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

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

[Jose Luis Rivero]

On Wed, Sep 03, 2008 at 06:19:53PM +0200, Sven Vermeulen wrote:
> On Wed, Sep 3, 2008 at 4:44 PM, Jan Kundrát <jkt@gentoo.org> wrote:
> > Camille Huot wrote:
> >>
> >> As a workaround, I would suggest to bump the date when an old document
> >> has been checked, tested and certified with current material.
> >
> > If I were yoswink, I'd kill you for such a change.
> 
> OMG they killed Cam !!

Not yet. But if someone touch the date for such proposes I will start
with the fingers and finish with the toes =). 

If we want to add metadata about checked/certified then we should use a 
separate tag. The date tag is for what it is.

> 
> And, to be on-topic: I'd rather keep the current system. Using a
> "touch" way is imo pointless and more prone to issues (for instance,
> fix a language typo on an outdated document shouldn't bump the date
> nor version as the document is still outdated).

No way of use "touch" for this *shrug*. I've ordered to my slaves that:
http://dev.gentoo.org/~yoswink/tmp/prepare-the-thing.jpg

> Removing the date will silence people who say documents are outdated
> (when they are not) but will probably create voices that would like to
> see a "last modified" date.

Yup, fix a problem creating another is a bad way to go.

> In my opinion, documents should always have a "last modified" date. If
> you want some sort of document lifecycle, you might want to introduce
> a revision period (for instance, every vital doc should be revised
> every 3 months, every other doc every year) and add in two headers:
> "last revision" and "next revision date"...

This belongs to another thread/discussion to me, since it seems like a 
new feature. Maybe too much to fix this problem.

-- 
Jose Luis Rivero <yoswink@gentoo.org>
Gentoo/Doc Gentoo/Alpha

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

[Jose Luis Rivero]

On Tue, Sep 02, 2008 at 07:14:44PM -0700, Josh Saddler wrote:
> Hi guys. I dunno about you, but I'm getting tired of folks bashing our docs 
> as being "out of date", "stale", "old", or "inaccurate" just because of the 
> displayed date of the last update.
>
> I propose that we keep the date inside the document code, for our own 
> internal purposes, but remove it from the final rendered page.

As swift has said in previous posts, keep the last change date visible is 
a quite useful while reading documentation.

>
> As you know, the date displayed has little relevance to when we last 
> actually touched-up the document, given our internal date bump policy.
>

Or I'm missing something or the date should reflect the date of the last
doc version.

>
> So. There's my proposal. Thoughts?
>

What about change 'Updated' to 'Last Change' being 'Last Change' a link 
which point to an entry in the FAQ explaining what is the last change
and why it doesn't imply that the doc is out of date.

Regards.

-- 
Jose Luis Rivero <yoswink@gentoo.org>
Gentoo/Doc Gentoo/Alpha

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

[Duncan]

"Sven Vermeulen" <swift@gentoo.org> posted
6de0e7060809030919m340af75dy2b0af22c8fa4f09c@mail.gmail.com, excerpted
below, on  Wed, 03 Sep 2008 18:19:53 +0200:

> In my opinion, documents should always have a "last modified" date. If
> you want some sort of document lifecycle, you might want to introduce a
> revision period (for instance, every vital doc should be revised every 3
> months, every other doc every year) and add in two headers: "last
> revision" and "next revision date"...

That's pretty much what occurred to me as well.  What seems to be missing 
is a "last reviewed on" date (revision suggests something other than the 
date in question changed, which may not be the case, thus I chose 
reviewed-on instead of your revised) to go with the last-updated date.  
The "next review due on" date would be nice too, but isn't really needed 
to correct this problem, I think.  Even if such may be desired, I believe 
a static link to a policy documenting the review period policy would be 
fine and being static, wouldn't need updated every time.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

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

[Chris Gianelloni]

[-- Attachment #1: Type: text/plain, Size: 1247 bytes --]

On Wed, 2008-09-03 at 18:33 +0200, Camille Huot wrote:
> In fact, if I understand correctly the terms of use of the Gentoo name
> and logo (http://www.gentoo.org/main/en/name-logo.xml), such sites (if
> not illegal by using gentoo in their domainname) HAVE to state
> explicitly that they're not official Gentoo.

That is correct.  An even better solution would be to have the
guidelines amended to enforce an obvious distinction between official
Gentoo documentation.  I consistently have to remind people that
gentoo-wiki is not owned, run, or maintained by Gentoo and has no
official affiliation, at all.

For example, on the main http://www.gentoo-wiki.com/Main_Page page, the
notice about not being official is *tiny* and almost hidden in
comparison to the other information on the page.  Pick any other page,
such as http://www.gentoo-wiki.com/Doom and you see no disclaimer,
anywhere.  While I do not believe that those guys are intentionally
trying to fool anyone, as they've been very understanding and helpful
any time I've dealt with them, it still does a disservice to Gentoo's
users.  By the way, not having the disclaimer on every page *is* a
violation, AFAICR.

-- 
Chris Gianelloni
Developer
wolf31o2.org

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 197 bytes --]