Re: Processing HOWTOs

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

David Lawyer wrote:
> 
> On Wed, Jan 26, 2000 at 10:21:54AM +0100, Stein Gjoen wrote:
> 
> > 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.
> 
> If a reader is not sure whether or not they should email the author,
> then it could be because what they have to say is not very important
> or possibly wrong.  Thus it's sometimes a good thing that people
> hesitate to write.

I disagree. In my experience, about 90 percent of all comments
comes wrapped up in such diplomatic language it would impress
professional diplomats. While I don't regard myself as
intimidating it seems the majority by far thinks otherwise. Also
the Slashdot article showed many had comments yet didn't want
to come forward.

Secondly I wish to make my HOWTO accessible to newbies too and feel
therefore that all comments are welcome; if the question is wrong
it just means my HOWTO is not clear enough and it is then MY job
to make it clear.

I feel a HOWTO should be something like
Intro + Reference + Step-by-step Guide + FAQ + Links
but I accept other authors have different views.


> > > 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.
> 
> I think the existing system is OK.  People write directly to the
> author.  Stats will be quite misleading as to the importance of a
> document.  Most distributions have the HOWTOs so a lot of people will
> not be going to websites to get them.  A document relating to
> a specialized topic on software development may be read by only a
> few people.  But if those few people are able to use this info to
> develop software used by millions, then millions benefit from the
> distribution of only a small number of documents.

My intended use of the stats is to measure success of web promotion,
based on my own experience the first few submissison engines hardly
gave any measurable increase. The later ones made a big impact by
nearly a factor of 10. A small note with a reference to my HOWTO
buried deep in a subthread on Slashdot doubled that again though
not surprisingly that was mainly a transient.

> Right now we need to spend more time recruiting people including
> people to review docs.

I agree this is important but I didn't think this is
an either/or situatiuon. Get me the statistics and I can
get the promotion underway.

> > Some actual hit stats from the LDP site would tell us how we
> > are doing.
> 
> There are about 200 mirror sites so it's quite a project.  An
> interesting situation is that if I use a search engine to find my
> HOWTOs, almost all of them found are out-of-date (some are over a year
> out-of-date).  Hopefully readers will go the the "New versions of this
> howto" section and get a new versions.  But many will not.  One to-do
> is to send form letters to sites that have stale HOWTOs and ask them
> either to update their HOWTO collection or replace them with links to
> a mirror site that has the latest updates.  Also it would suggest that
> they might become a mirror site and thus would not be out-of-date
> anymore.

Out of sync mirrors is a problem, agreed. Sadly also many
distributions use out of date HOWTO collections. I hope we
can persuade the distribution makers to keep fresh collections
in their errata pages.

This brings up another problem: now that several HOWTO authors
have left LDP for OSWG it could be a little more complicated
to compile HOWTOs for the various distributions. Looking at
	http://www.oswg.org/
I see more and more HOWTOs being added.

I do wonder if all distribution makers are aware of the split, I
have suggested in the past to actively persuade them to join this
list. Alternatively the LDP could make RPM packages ready to go
(the Debian people are subscribed already) to make sure they get
the very latest with a minimum of pain. Should we add a link to
the OSWG site? It could benefit the end users.

> > >    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.
> I don't agree.  For one, I don't like frames to well and they are a
> pain with the Lynx browser.  Reviews are best done by people who know
> the topic.  A HOWTO may be well written but contain a lot of errors.
> If the errors are on options that few people use (or on "theory"),
> they are likely to remain unreported.

I agree that <FRAME> is a pain but <TABLE> should work well.
I do not agree that reviews are best done by people who know
the topic ALONE, a newbie can very well have valuable inputs
on what is unclear while the experts can take too much for
granted.

> What we might do is to have a HOWTO feedback article which is linked
> to from the LDP home page.  It would suggest that readers give
> feedback to the author if they find something wrong.  Also, it would
> state that if someone finds a HOWTO with an excessive number of typos,
> awkward sentences, or lack of clarity they should report it to the
> HOWTO Coordinator.  In such a case the HOWTO Coordinator would check
> it out.  If there is no hope that the author alone can fix it, then
> perhaps someone can be found to edit the authors work.

I already have several notes in my HOWTO that I welcome feedback
but still they seem too scared to speak up. Can you tell us more
on your own experience on feedback?

I did once get feedback via the Debian error tracking system.

> > > 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, ....
> 
> "Hoards" is an exaggeration.  But I've had multiple people report the
> same mistake when there was a 2 month delay in getting the HOWTOs
> uploaded.

Has there been any problems with hoarding? No need to name names, I
am just curious.

Regards,
   Stein Gjoen


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