discuss: the good the bad and the ugly
Subject:
Re: the good the bad and the ugly
From:
David Lawyer ####@####.####
Date:
20 Nov 2003 07:03:39 -0000
Message-Id: <20031120070127.GB776@lafn.org>
On Wed, Nov 19, 2003 at 11:40:22AM +0530, rahul wrote:
> On Wednesday 19 November 2003 08:42, Tabatha Marshall wrote:
> Any outdated docs should be marked as such. any docs having potentially wrong
> information should be pulled out immediately.
You don't really mean this I hope. It all depends on more than just
errors. For example, errors in explaining theory may have little
adverse effect in practical results. But even if there is no wrong
information but it's very poorly written and the same material is covered
better elsewhere, then I think it should be pulled (sort of). Before
doing this, the author needs to be given a chance to fix things.
[snip]
> Go through every single doc that you can in the ldp and present
> comments. lets discuss this and make a improvement. In about 2 to 3
> months(what i have in mind) we should see marked improvements.
You've got to be dreaming. We would need many more volunteers to keep
this schedule.
> After clearing all these docs we will have to work on screenings
> incoming stuff. every doc should go an technical as well as language
> review. we have reviewers who will take care of the language.
The new stuff is perhaps more important than the old. If the original
submission is good, updates are likely to be almost as good. Thus I
think that technical review of new docs is even more important than
technical review of old docs.
When an author of a good original doc submits an update, one might hope
that it would of even better quality than the original but
unfortunately, it's apt to be worse. One reason for declining quality
of updates is that there's a strong temptation to try to simply
incorporate new developments within the existing organization and
framework of a HOWTO, while what's needed is complete reorganization in
light of new developments.
> Technical reviewing is much more harder because it is likely to
> diversified. So we will have to rely on public feedback. We need to
> work on getting more feedback.
The way it should work now is that one just clicks on the author's email
in the header of the doc. But some authors don't have their email
there. Many have their email written so that robots can't get it but
then one has to type it manually to send any email and this may be too
much bother for some. Some authors may not disclose their emails.
> This is what a content management system or wiki would give us.
A wiki imposes a lot of work for the author. The author must look at
what someone has changed in a wiki, compare it to the original, and
perhaps wonder why the reader did what s/he did. An email to the author
should be better.
Furthermore, with an email, the reader just mentions the problems and
doesn't need to go thru all of the work of solving them by revising the
doc. In many cases, the reader knows something is wrong but doesn't
know how (or have time) to fix the problem. For example, the reader my
find a broken link, but doesn't know if there is a new link to this
topic. So the reader would just report a dead link and let the author
try to find a new replacement link.
> It would enable us the framework to receive very quick feedback. Today
> I dont have a way to determine the quality of these docs. No
> statistics. which of the docs are being read more?.
There's no way to really determine which docs are being read more. One
could keep track of on-line reading of html docs. But the longer ones
will tend to be read off-line.
> which of these docs are ignored. How do users feel about it.
> They will have to email the author for feedback which isnt the quick
> way to do it.
What quicker way is there to contact the author than via email? Sure, a
copy could go to us at LDP but it's the author that must act on it and
make changes.
> We need the framework and we need it now.
Yes, we need it but what would you propose? I think that any system of
feedback should be done by allowing a reader to just click on an email
address in an html doc. Ideally, email comments would go to both the
author and LDP. It would be something like a bug tracking system. Then
the response from the author is also CCed to LDP. If the comments are
valid suggestions for improvement, then a check needs to be made to see
if the doc is updated as a result. Who at the LDP is going to handle
all this? There may be cases where the author doesn't respond or
responds with a note that they hope to check it out later on, etc.
So it can't really be automated. An automated system can report whether
or not an author responds. But it can't report whether or not the
response is a "good" one. Readers could complain about responses, but
will they complain if the author says they don't have time to fix it, or
the fix has not fully satisfied the reader. Who at LDP will handle all
cases where there are complaints? I might add that bug reports to
Debian have sometimes taken years to get a response.
A good way to solve these problems is to have a database that will let
authors ask for a coauthor or put their doc up for adoption while still
maintaining it. Then we have to recruit new authors to do the work. To
help in this regard, I think that we should emphasize simple linuxdoc
and not suggest that they use docbook. This should be emphasized at the
start of the author's guide and present new authors them to skip over
all the parts describing docbook (and markup in general).
Also, we need to have subject coordinators who handle a certain related
set of HOWTOs, etc. The subject coordinator such as say the "Network
Coordinator" would track all such HOWTOs regarding networks and make
sure they are all up-to-date. It would be much more work than
just maintaining some HOWTOs. Such a coordinator would just offer
suggestions and people wouldn't have to necessarily follow them. But it
would help. For serious problems that they were unable to cope with
they could write to the discussion list.
There's the problem of finding good subject coordinators that both have
time to do it and know the subject. It's more work and skill than being
an author but likely gets less recognition. Perhaps the best people to
do this would be current authors of good HOWTOs that have the time to do
it.
David Lawyer
