RE: LDP bug-tracker

[bf347@lafn.org (David Lawyer)]

M> From: garym@canada.com (Gary Lawrence Murphy)
M> Subject: Re: LDP bug-tracker
M> To: bf347@lafn.org
M> Cc: ldp-discuss@linuxdoc.org
M> Reply-To: garym@canada.com (Gary Lawrence Murphy)

  "D" == David Lawyer <bf347@lafn.org> wrote:
  "M" == Gary Lawrence Murphy <garym@canada.com> responded:

    D> Why do we need a bug-tracker?  It's nice to do this for
    D> software but for documents I'm not so sure.  For software, a
    D> bug keeps some people (or everyone) from using it.  For docs
    D> this is seldom the case.

M> With far too many LDP docs, this is exactly the case: Many docs
M> describe the system as it was in 1998 and with 2.2, there have been
M> many fundamental changes.  

Although the out-of-date document may be of little use to someone that
is using the latest version, one can often find the needed info
elsewhere on the web, etc.  A bug in the docs can be worked around
easier than a bug in the software (which may make using the program
infeasible).

M> I'm not thinking of the bug-tracking as
M> a means to announce fixes as much as a means for visitors to the
M> LDP to report an error and propose a fix, then have that info relayed
M> to the author.  Also, a bug tracker could be used to tell the LDP
M> admin people that a fix has been sent and alert them to post it.

A reported "bug" with a doc should normally go thru the
maintainer/author who may determine that it really isn't a "bug" after
all.  People who use howtos may not bother to look at the postings re
howto bugs.  It would be best to append this to the howto, or better,
to fix the howto and that's best done by the maintainer.  An important
bug should result in an update to the howto the next day.  This will
be more feasible with automated submission.

    D> ...  This may be a lot of unnecessary bother, especially if all
    D> that was fixed was a typo

M> For this case, we need an automated publishing system, perhaps based
M> on XML, where small changes to the master archive (CVS?) are simply
M> checked in and exported by a periodic cron job.

It's simpler for those who don't know anything about CVS to just email
in a revised version (which can be automatically uploaded).

    D> ...  I think that the best system is for the author (or
    D> maintainer) to have a "mailto" url link at the start of the
    D> howto.  

M> In my search for authors (I have 40 new books in need of contributors)
M> my first line of research is to approach LDP authors because I'd like
M> to see them get a bit of pocket money for doing what I already know
M> they enjoy.  The trouble is, with many HowTos the address is no longer
M> valid.

Why would an automated bug-tracking system be significantly better in
getting a response from the author or maintainer?   If the tracking
system is able to find the current email of the author, why couldn't
the same means of finding the correct email be used to put this updated
email address into the doc?

    D> ...  For software bugs it's often desirable
    D> to have a number of people listening in since they may be able
    D> to figure out the cause of the bug (or report other symptoms)
    D> and help fix it.  This is seldom the case with docs.

M> I disagree.  Docs which may be true for RedHat may not be valid for
M> LinuxPPC or even for RH Alpha.

It's not really a bug if a doc doesn't cover how to do it for PPC or
Alpha.  Many docs only cover how to do it for PC's.  People reporting
a problem in a doc usually have a fix for it.  What we need is many
more howto authors.

    D> if defects in documents are to be publicized, people might be less
    D> inclined to write howtos (and also less inclined to release it
    D> when they should).  Someone that wanted to criticize an author
    D> could gather a lot of ammunition if a bug tracking system
    D> existed.

M> Why would anyone want to maliciously attack the author of a free
M> document?

It's going too far to call "criticize" a malicious attack.  But
critical comments which reflect aversely on people happen all the
time, including in this newsgroup.  Some are justified, others are
just teasing, and others are ...  Ad hominem attacks are very
frequent, just look at politicians.  It happened frequently to me when
I tried to reform a mismanaged organization.

			David Lawyer


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org