Mailing List Archive

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

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

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

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

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

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

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

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

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

"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

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