discuss: Thread: Debian, et. al. distributing stale LDP documentation

I wrote this after I couldn't find documentation I needed on my PC due
to Debian's mis-conceived policy.

			David Lawyer
<!doctype linuxdoc system>
<article>
<title> Why Everyone Should Distribute Only the Latest HOWTOs
<author>David S.Lawyer <tt><url ####@####.####
<date> Feb. 2006

<sect>Introduction
<p>The Debian distribution is using stale packages of LDP HOWTOs
(packages named doc-linux-text, etc.) in their testing and stable
distributions of Linux.  Why?  It's because they are handling
documentation like one handles software: the very latest revision of
software is more likely to have serious bugs, so it's safer to use
previous versions that have gone thru a testing period.  But this
policy is ill advised for documentation because documentation is of a
much different nature than software.  The policy of Debian and others
needs to be changed to always distribute the latest HOWTOs.  This
article will explain why.

There are 5 reasons that support the conclusion that the only the
latest revision of documentation should be distributed and that the
latest revision of documentation is relatively better than is 
is the case for software.

<itemize>
<item> Documentations becomes more buggy as time goes by
<item> Documentation bugs are easier to work around
<item> Users are less likely to report documentation bugs 
<item> Documentation writers are often behind in their work
<item> Revision of Documentation is less likely to introduce serious bugs.
</itemize>

Let's discuss these one-by-one.

<sect>Documentations Becomes More Buggy as Time Goes By
<p>Even if documentation is accurate when it's written or revised, it
becomes buggy over time as software and hardware change.  But software
isn't supposed to become buggy over time since other programs that
interact with such software are supposed to be backward compatible.
This means that the new software should still be able to work with the
old software, resulting in no introduced bugs in the old software.
It doesn't always turn out this way but software in general becomes
buggy at a much slower rate than documentation.  Thus it may not be
such a bad idea to distribute older software that has stood the test
of time.

What about the situation for documentation?  When new hardware is
designed, do the hardware designers say: "We must design this new
hardware so it will be backward compatible with the existing
documentation"?  Do software developers say: "We must design this new
or revised software so it will be backward compatible with the
existing documentation"?  Sometimes, but not usually!  

Thus documentation becomes buggy and obsolete with the introduction of
new hardware and software designs.  And since the introduction of
newer stuff is a usually continuing process, documentation becomes
much more buggy over time than software does.  Thus if you distribute
old documentation, you are more likely distributing buggy documentation.

<sect> Documentation Bugs Are Easier to Work Around
<p>If there's a bug in software, it's not very easy for the user to
fix.  If the user is a programmer, it might not be as difficult.  One
can submit bug reports and hope that the software problem gets fixed
by someone else.

For a documentation bug, one can immediately search the internet for a
solution and usually come up with a solution much quicker than for the
case of a software bug.  One doesn't need to be a programmer to do
this or have to wait for someone else to do the programming and fix
the bug (which may take days, weeks, or months).  Thus it's much more
critical to insure that software is free from bugs than for the case
of software.

In many cases the documentation can still be used satisfactorily even
if it has a number of bugs.  Documents with misspellings and awkward
sentences can still be utilized to get the information one needs.

<sect> Users Are Less Likely to Report Documentation Bugs 
<p>Since documentation bugs are much easier to work around than
software bugs, most users just don't bother to report documentation
bugs.  Also, if a reader notices that a HOWTO is hopelessly out of
date or poorly organized, the reader realizes that the maintainer of
the document must already know this, so why bother to contact her and
tell her what she already knows.  For software, it's a different story
since reporting the bug may help get it fixed so that you can use the
software.  Thus there's a much stronger self-interest motive to report
software bugs.

Thus the Debian policy of allowing documentation to undergo a testing
period where readers will point out most of the bugs, is likely to be
counter-productive since the bugs don't get reported.

<sect> Documentation Writers Are Often Behind in Their Work
<p>While programmers may be able to document their software at about
the same time the software is written, people who write on the
integration of hardware, software, etc. are likely to be behind in
their work, especially if they are unpaid volunteers.

This means that even if you have the latest documentation, it is not
likely to cover the very latest software and hardware.  Thus, the best
that can be done by distributors of documentation is to distribute the
latest versions of the documentation without delay since there has
already been significant delays in producing the documentation itself.

<sect>Revision of Documentation is Less Likely to Introduce Serious Bugs
<p>Documentation is much different than software since there should be
a lot of redundancy in documentation.  Make a several mistakes in
software and it's likely not to work right, if at all.  But make
several mistakes in documentation and it's likely to be still be
usable since readers can often make sense of errors like misspellings,
awkward expression, etc.  Even more serious bugs may be often be
worked around by searching the Internet.

For example, put a few extraneous letters or words in a document and
it still is apt to make sense.  But do this to a computer program and
it likely will not work right, if at all.  Thus revised documentation
is much less likely to contain serious bugs as compared to
documentation.  Thus there is less danger getting bugs if one
distributes the latest versions of documentation.

<sect>Exceptions: Revised Documentation Can be Worse <p>There are
examples of where revising documentation makes it worse.  This can
happen if the person revising it is either incompetent, malicious, a
prankster, etc.  If this person is also the document's author, then
the revision may not be much worse than the previous inferior
document.  But a danger occurs when someone who is malicious or
incompetent takes over someones else's document and revises it.  This
can make the revised document significantly worse than the previous
one.  This has actually happened at LDP.  LDP now has a review process
so that this situation is less likely to happen now.  While it can not
be unequivocally stated that a revised of document will be better than
the previous document, the author believes that under present
conditions it will almost always be better.

<sect1>Conclusions
<p>Organizations and individuals who distribute LDP HOWTOs (and most
other documentation) should always distribute the latest versions.
Well, for historical purposes, one might want to make old versions
available, but they need to be clearly labeled for what they are.  A
survey made by the author a few years ago found that, excluding the
LDP mirror sites, the majority of LDP HOWTOs at other sites were
out-of-date (sampling was only done for Modem-HOWTO).  So distributing
stale documentation is not just a problem associated with the Debian
distribution of Linux.

</article>

David Lawyer said on Tue, Feb 14, 2006 at 09:48:17PM -0800,:

 > I wrote this after I couldn't find documentation I needed on my PC due
 > to Debian's mis-conceived policy.

Debian `unstable' has a snapshot of doc-linux-* for 2005.12-1.

I Really do not think `stable` will accept anything except what was in
there when the repository was declared to be `stable`.

I guess something can/should be done about testing. (Currently, etch).

 > 
 > 			David Lawyer
 > <!doctype linuxdoc system>
 > <article>
 > <title> Why Everyone Should Distribute Only the Latest HOWTOs
 > <author>David S.Lawyer <tt><url ####@####.####
 > <date> Feb. 2006
 > 
 > <sect>Introduction
 > <p>The Debian distribution is using stale packages of LDP HOWTOs
 > (packages named doc-linux-text, etc.) in their testing and stable
 > distributions of Linux.  Why?  It's because they are handling
 > documentation like one handles software: the very latest revision of
 > software is more likely to have serious bugs, so it's safer to use
 > previous versions that have gone thru a testing period.  But this
 > policy is ill advised for documentation because documentation is of a
 > much different nature than software.  The policy of Debian and others
 > needs to be changed to always distribute the latest HOWTOs.  This
 > article will explain why.
 > 

BTW, debian is unlikely to treat  anything which is carried on its ISO
images /  servers as anything except  software. That is  why it treats
the GNU Free Documentation license as non-free. 

 
-- 
Mahesh T. Pai   ||  http://paivakil.blogspot.com
Distributing free copies of non-free software is --
        -- like advertising drugs.

David -

Begging the indulgence of the other subscribers of this list, since your email
is still blocked, be sure to pick up the message I left for you on the
####@####.#### list last month.  It is message 294, subject: Suggestions
for Serial HOWTO, dated 23 Jan 2006.

[This assumes that tldp.org is not also blocked by lafn.org.]

--
Chuck Brockman