discuss: Thread: Stale Docs (was: My obsolete HOWTOs being sold as a book)

I have to say that I don't think scary licensing or boycotting is the answer
to this problem. I think the solution is twofold. First, readers need to
take a certain amount of responsibility in making sure they are reading the
latest version of a doc. Second, we need to make it as easy as possible for
readers to find the latest version of a doc. I think the LDP is doing a good
job of both of these, and certainly the latest cleanup/database effort will
make things even better.

So how do we give users the tools to take on that responsibility in the
easiest/friendliest way possible? I think there are plenty of models for
this on the software side. Debian provides a good solution. They supply a
packaging standard and installation tools for users and developers as well
as websites with the latest (more or less) versions of everything. Perl has
CPAN, etc.

The role that I think LDP should play is to provide a standard for
documentation, tools for meeting those standards and a central repository of
the latest documentation.

<soapbox>

Along those lines, I would personally like to see the LDP move away from the
current classification scheme that requires one to decide up front whether
to look for a guide, howto, mini, etc. Every time I go to the LDP I am
looking for the answer to a question about a topic. I couldn't care less
what form that answer takes and it aggravates me to have to look in multiple
places. Sure I can do a search, but that has its own drawback. I'm not
saying that the classification scheme has no value at all. I just don't
think it should be the driving force behind how the documents are accessed
via the website.

Imagine going to a library to find a book and having to know in advance
whether it was a big book or a little book, whether it was hardcover or
softcover, whether it had pictures or was all text. Those are all useful
attributes about a book but shouldn't dictate how I go about *finding* the
darn thing. Subject, author, title - those are the primary attributes. Why
doesn't the LDP have navigation based on subject, author and title?

</soapbox>

---
Patrick K. O'Brien
Orbtech (http://www.orbtech.com)
"I am, therefore I think."

On Mar 1,  9:49am, Patrick K. O'Brien wrote:
> Subject: Stale Docs (was: My obsolete HOWTOs being sold as a book)
> ...
> Imagine going to a library to find a book and having to know in advance
> whether it was a big book or a little book, whether it was hardcover or
> softcover, whether it had pictures or was all text. Those are all useful
> attributes about a book but shouldn't dictate how I go about *finding*
> the darn thing. Subject, author, title - those are the primary
> attributes. Why doesn't the LDP have navigation based on subject,
> author and title?

We're hoping the OMF search capability solves that problem (once
all docs are properly classified within their system).  No sense
re-inventing the wheel:

  http://www.ibiblio.org/osrt/omf/#search

In fact, at some point I'd like to see this become the primary
search for the LDP, rather than my wais-based hack.

The time and effort to catalog *all* the LDP docs within the OMF
framework would be time well spent, imo. I originally submitted
a slew of XML data records to be used in the system, but at this
point many are out of date.

r,

-- 
Greg Ferguson     - engr / mtlhd / enemyofthemusicbusiness(.com - ND)
SGI Tech Pubs     - http://techpubs.sgi.com/ | gferg (at) sgi.com
Linux Doc Project - http://www.linuxdoc.org/ | gferg (at) metalab.unc.edu

On Thu, Mar 01, 2001 at 09:49:46AM -0600, Patrick K. O'Brien wrote:
> I have to say that I don't think scary licensing or boycotting is the answer
> to this problem. I think the solution is twofold. First, readers need to
> take a certain amount of responsibility in making sure they are reading the
> latest version of a doc. Second, we need to make it as easy as possible for
> readers to find the latest version of a doc. I think the LDP is doing a good
> job of both of these, and certainly the latest cleanup/database effort will
> make things even better.
> 

I'm attaching a report on my survey of stale copies of my Modem-HOWTO.
I think the situation is about the same for other howtos that are
frequently maintained.  There are likely several hundred websites that have
out-of-date LDP documents (I found about 500 just for my Modem-HOWTO).
People in the know will check out our LDP mirror sites to find an
up-to-date doc.  But if one has a problem and wants an answer they are
likely to go to a general-purpose search engine such as Google,
AltaVista, Excite, Yahoo, etc.  Then they may find a LDP doc in the
search and it may be out-of-date.  I'll try experimenting with this.
It depends on the search engine.

If the search engines could determine the date/version of the doc and
give preference (list first) to the most recent one it would help.
Since many sites add material to the head of the doc, the file date is
often more recent than the date of the doc.  Even if search engines
could find the date within the doc, some sites might automatically
change the dates of their docs without actually updating them in order
to get more traffic to their site.

What can be done is to contact authors of introductory Linux material,
ask them to mention the LDP, and suggest the use of LDP mirrors so
that the docs they get will be fresh.  If the Debian distribution
could automate the packaging of LDP docs and update every week or so,
that would help also.

			David Lawyer

		Stale HOWTO Survey (for Modem-HOWTO)
		by David S. Lawyer, Mar. 1-2, 2001

The table near the end of this file show the number of web-pages with
stale (old versions) of my Modem-HOWTO.

I searched using google.com with search terms:
Modem-HOWTO "modulation details" v0.xx
Where xx = 00, 01, 02, etc.  The phrase ""modulation details" is from
the table-of-contents so as to always select the HTML table of
contents file (for split HTML-HOWTOs) .  This is needed since v0.xx is
sometimes also in chapter 1 and used so that readers can click on a
link to LDP and see if they are looking at the latest version.  If
"modulation details" were omitted there would be double counting.
Also, "modulation details" removes hits on lists/catalogs of
HOWTOS.

My "change log" also lists version numbers but it's inside comments
and should only be in the sgml version.  However, for v0.02, 20
web-pages had included it so 20 was subtracted from the hits on v0.00
and v0.01 to eliminate double counting. Note that Google didn't find
any sgml versions which is bad news if someone wants to get the
source.  

Modem-HOWTO.  Last col. is number of web-pages having it per Google on
Mar. 2, 2001:

v0.14 Feb. 2001   0
v0.13 Feb. 2001   0
v0.12 Dec. 2000  76
v0.11 June 2000 118
v0.10 May  2000  60
v0.09 Mar. 2000  18
v0.08 Jan. 2000  61
v0.07 Nov. 1999   3
v0.06 Nov. 1999   2
v0.05 Oct. 1999  17
v0.04 Aug. 1999  64
v0.03 May  1999  11
v0.02 Mar. 1999  73
v0.01 Jan. 1999  58
v0.00 Dec. 1998  63

Note that it seems Goggle often reports fewer web-pages when it's
heavily loaded with search requests.  Thus one may get results lower
(or higher ??) than shown above.  For this reason the sum of the above
(661) is not what one obtains by searching for unique text in the
HOWTO.  There could be another reason too so I could be wrong although
I've run the same search over a few times and got counts that vary by
say 50% or so.  I'll check again when it's daytime in low-density
computer regions (the Pacific Ocean/Asia).

In some cases the link may be dead or updated since Goggle last
checked them.  But a spot check indicated that roughly 80% of them
still exist as listed.  In one case I found a stale one in an
"/archives" subdirectory which is OK since the word "archives" in the
path name implies that it's stale.  A number of the sites shown by
Google to have v0.12 actually had v0.14 (the latest version).  The
number of sites that carry the HOWTO is somewhat less than shown,
since some sites have multiple copies in various formats, etc.

On Fri, Mar 02, 2001 at 08:46:12PM -0800, David Lawyer wrote:
> 
> I'm attaching a report on my survey of stale copies of my Modem-HOWTO.
> I think the situation is about the same for other howtos that are
> frequently maintained.  There are likely several hundred websites that have
> out-of-date LDP documents (I found about 500 just for my Modem-HOWTO).
> People in the know will check out our LDP mirror sites to find an
> up-to-date doc.  But if one has a problem and wants an answer they are
> likely to go to a general-purpose search engine such as Google,
> AltaVista, Excite, Yahoo, etc.  Then they may find a LDP doc in the
> search and it may be out-of-date.  I'll try experimenting with this.
> It depends on the search engine.

David, I wrote several days ago about including your report in the
LDPWN. I haven't heard back from you and today is my deadline, so I am
including it without your specific permission, on the rationale that
you sent it to this public forum. Scream and I'll take it out - other
press are linking to us now instead of reproducing so I can do that
easily.

-- 
Dr. David C. Merrill                     http://www.lupercalia.net
Linux Documentation Project                   ####@####.####
Collection Editor & Coordinator            http://www.linuxdoc.org
                                       Finger me for my public key

/*
 * Oops. The kernel tried to access some bad page. We'll have to
 * terminate things with extreme prejudice.
*/
die_if_kernel("Oops", regs, error_code);
(From linux/arch/i386/mm/fault.c)