Processing HOWTOs

[Stein Gjoen <sgjoen@mail.nyx.net>]

Gary Lawrence Murphy wrote:
> 
> 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.

In my experience the readers are too timid to approach the authors
directly, a semi anonymous web log, perhaps for each document, would
perhaps lower the threshold and give us more feedback.

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

Sadly true. So when is the core team going to post a request
for new authors or maintainers on news:comp.os.linux.announce ?
It wouldn't cost to try.

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

In the 4 years or so I have maintained the Multi Disk HOWTO I have
only had 3 in depth comments from readers; that is not much and I
would like more.

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

To get proper stats we also need to promote. I did some automated
web promotion of my HOWTO and raised the hit counts from
about 50 a day to 300-500 a day. What has the core team done in
this respect? This is hardly the firt time I ask/suggest but I
have yet to see an answer. Some actual hit stats from the LDP
site would tell us how we are doing.

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

Good idea, I second this.

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

Again this is not the first time this topic comes up and many
authors were approached by a 3.rd party willing to take up that
job. Nothing has been heard of since.

I proposed an automated cooperation with Freshmeat, another idea
that sunk mostly without a trace. Yet when I check the place
	http://freshmeat.net/search.php3?query=HOWTO
I find 17 HOWTOs have quietly been registered, and tracking
numbers and dating is done, an example:
	http://freshmeat.net/appindex/1999/06/26/930410556.html
Looking closer I notice it is possible for users to make
comments directly to those web pages. It does look like
Freshmeat ALREADY has done what we have talked about.

Secondly being tracked in the Freshmeat database also
means your updates will automatically be announces to
Linux Weekly News.

Looking closer I see some more interesting programs, check out
	http://freshmeat.net/appindex/1999/04/01/922967500.html
	http://freshmeat.net/appindex/1999/09/20/937809864.html

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

I suggest we get a TODO list of good ideas up. Many ideas come
up again and again and sink without trace. I think even a TODO
list was mentioned some time ago but funnily enough nothing
happened.

In the absence of LDP activity other entities have taken up the
slack. rather than gnashing teeth over this I suggest strongly
we start cooperating as soon as possible.

Regards,
   Stein Gjoen


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