Re: mini-HOWTO

[Gary Lawrence Murphy <garym@canada.com>]

As we say in North America: "Close but no cigar" or perhaps "standing
on the right road, but going in the wrong direction"

>>>>> "G" == Gregory Leblanc <gleblanc@cu-portland.edu> writes:

    >>  I think the LDP should insist on being notified *before*
    >> people start writing. 

    G> That IS part of what the LDP is here to do.  If one reads the
    G> LDP website, and/or the HOWTO-HOWTO (I can't remember where it
    G> was) it says that you should attempt to contact the HOWTO
    G> coordinator before you begin writing anything.  

And indeed it does.

    >>  It's a big problem of image, quality must be much more
    >> important than quantity, and people must be used to this. 

IMHO, while the LDP is amazing, let's not kid ourselves about quality.

The quality control is non-existant.  There is no tagging of documents
to versions, no consistency of distribution variations, no tracking of
user stats and no stakeholder review, and many ancient docs which
should be weeded out are kept because "they are all we have on that
subject".

The LDP is, however, still _amazing_ : it is amazing that it exists at
all, entirely out of volunteer labour and community support.  Even the
FSF spawned nothing like it despite a 10 year head start.  But let's
be real here: We have no docs, not one, in the entire LDP collection
to compare with the EMACS, ELISP or GLIB manuals from the FSF.  Those
are quality works worthy of being published as books.  What we have
are disjoint read-me's and man pages by comparison.

    >> *must* be strict technical review, and only good documents must
    >> be approved. At least, there must be a "blessed" set of
    >> documents and a "mass" of contributed stuff, either badly
    >> written, or incorrect, or just redundant of other documents.

And who does this judging?  We could also use some editorial revisions,
but it won't happen without a business plan; it's hard enough to find
people to create documents, but to ask someone else to revise them is
somewhat pushing the realm of possibilities.

    >>  To this aim, we need a charismatic leader or group of leaders,
    >> who can accept and refuse works without offending anybody.

No, we need a process whereby docs can be rated and comments attached
by the user base.  We need stats to show which docs are actually read,
and a followup process which asks the reader if the doc was actually
helpful.  This is basic Customer Support 101.

Maybe we should treat authors like software authors: When someone is
the maintainer of a software package, they put their email address on
it. They _expect_ to receive bug reports and gripes which are then
folded back into the software to improve it.  When it gets to be too
much for them, they hand the reigns to someone else.

   How about this: A new display engine on the website which lists the
   requested doc in the right frame, but down the left margin lists
   the title, the date, author contact info and the version numbers of
   mentioned software.  Below this is a survey form that says "How
   useful is this doc?"  Then, once we have a significant database of
   reviews, when someone searches for a doc, the search results page
   shows the title of the document followed by its review metrics, its
   age and the version numbers.

Maybe a requirement for LDP authors should be an explicit ownership
clause in the submission process which says "You agree to maintain
this component" --- if someone doesn't want the great hoards of users
sending them email to complain about a typo, them maybe an LDP doc is
not for them, or they should add their doc to the "unmaintained" list.

Part of this is also proper dating of material.  All LDP docs should
say right at the top the date of last revision, and the search engine
results must tell me this.  What good is it to find a ppp-2.1 or a
kernel-2.0 doc?  Maybe I really am looking for help with old
technology, but I will bet real money most queries against the LDP
search engine are looking for help with the most recent Linux
distributions --- the vast majority of the Linux users out there today
have been using Linux for less than a year.

    >> This is how free software works: there always is a maintainer
    >> who accepts and refuses contributions, and nobody ever sends in
    >> stuff pretending it gets accepted.

And so there should be, but, like software, we want a maintainer for
each and every doc, not one all powerful overlord for the entire
collection, and like freshmeat, the LDP need not pass any judgement
but let the community at large determine the worth of each.

-- 
Gary Lawrence Murphy <garym@linux.ca>: office voice/fax: 01 519 4222723
TCI - Business Innovations through Open Source : http://www.teledyn.com
Canadian Co-ordinators for Bynari International : http://ca.bynari.net/
Moderator, Linux Education Group: http://www.egroups.com/group/linux-ed


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