discuss: the good the bad and the ugly


Previous by date: 23 Nov 2003 18:19:54 -0000 Re: TLDP DocBook pages need work - Start there!, John R. Daily
Next by date: 23 Nov 2003 18:19:54 -0000 Re: TLDP DocBook pages need work - Start there!, John R. Daily
Previous in thread: 23 Nov 2003 18:19:54 -0000 Re: the good the bad and the ugly, David Lawyer
Next in thread: 23 Nov 2003 18:19:54 -0000 Re: the good the bad and the ugly, David Lawyer

Subject: Re: the good the bad and the ugly
From: David Lawyer ####@####.####
Date: 23 Nov 2003 18:19:54 -0000
Message-Id: <20031123083930.GH404@lafn.org>

On Thu, Nov 20, 2003 at 08:00:10AM -0500, Randy Kramer wrote:
> On Thursday 20 November 2003 02:01 am, David Lawyer wrote:
> > On Wed, Nov 19, 2003 at 11:40:22AM +0530, rahul wrote:
> > > 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.
> 
> A wiki can be used in many ways, and a reader, recognizing a problem in a 
> document could, as you say, revise the document, or simply add a note 
> indicating a problem.

Wouldn't just an email to the author be better.  How often will authors
check their wikis?  Wouldn't it be easier for the author to just check
email since they are checking email anyway for other types of mail.

> 
> If a particular author wishes to get comments only rather than revisions, his 
> wish could be enforced by installing the comment plug in (in TWiki) -- IIRC, 
> the TWiki page can be made unwritable yet still accept comments via the 
> comment plug in.
> 
> Finally note that some wikis (notably TWiki) keep page content under revision 
> control (RCS) so that changes can be easily identified.  (Granted, the 
> presentation is not the word style diff that I would prefer, but it is 
> usable.)
Doesn't look good to me.
> 
> > 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.
> 
> So, in accordance with my comments above, the same approach could be followed 
> on a wiki, and the author does not have to publish his email address.
> 
> > > 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?.
> 
> For documents that are "published" on the TWiki, "hits" are recorded in a log 
> file, and hits for the top ten pages are (semi-)automatically summarized 
> (i.e., by a job that can be started by cron).  The hits in the log file for 
> all pages could be summarized, or checked by simple Linux utilities (grep and 
> wc).
This is only for the wiki online.
> 
> > 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.
> 
> Agreed.  (Although I do more and more of my reading online -- I hope I'm not 
> ruining my eyes ;-)
> 
> > 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.
> 
> Email can be somewhat problematic for the author if he is not well
> organized.  (I'm guilty of such.)  The author needs to save those
> emails somewhere, and find them again when he is ready to tackle
> modifications to the document.

No.  As soon as one gets an email they can make the changes (unless
it involves rewriting a long section, etc).  But most feedback is for
stuff that can be done right away.  One reason for doing it fast is that
then you can reply to the author and say it's been done.  In fact, I
often make changes while in the midst of reading the email.  Also, I get
less feedback than I used to implying that LDP documentation is not
being as widely distributed as it once was.

> Many readers may send him the same comment because they don't know
> that someone else has mentioned a problem.

This has only happened once to me, out of say a hundred comments on 4
HOWTOs over several years.  If an error found is serious, the author
should change it at once and submit the revised doc the same day.  This
helps avoid redundant comments.

> 
> If the document (and comments, or even just the comments, without the 
> document) are on a wiki, other readers can see what comments have been made 
> and:
>    * avoid redundant comments 
>    * clarify possibly misleading comments 
If email is sent to the author, the author does this.
>    * answer questions raised (explicitly or implicitly) for the author or 
> other readers

This is done on mailing lists, and also by authors.  Most email I get is
asking for help and involves questions.  Sometimes a request for help
results in adding something to the HOWTO that wasn't covered or in
modifying something that was unclear to some.

> 
> Further, when the author goes to modify the document, the wiki provides a 
> single source for many of the comments.

I now get less than one comment a month per HOWTO.  So I don't save up
comments and work on them.  I normally make the changes right away.

> > > We need the framework and we need it now.
> 
> I agree, and I can put pages on WikiLearn within a few hours of someone 
> providing text in a suitable format.  (Ideally, plain text, no indented 
> paragraphs, ... some other points that can be worked out.)  (I've even 
> thought (for my own purposes) that a DocBook stylesheet could be created to 
> output HOWTOs with TWiki markup.
> 
> > 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.
> 
> Re the last five paragraphs: So when can a system (even a prototype) be in 
> place?  

Above, the only project that I considered important was that of subject
coordinators.  This requires only people who know the subject and have
the time.  It doesn't really require any software but it would be nice
to have a uniform database to keep track of things.  Each subject
coordinator would need to keep track of the docs they cover and we could
just ask them to use plain text files for now.  Then when we get a
database they could enter it there.  It would be faster if each such
coordinator had their own files on their PC to keep track of HOWTOs
offline, and then could somehow have their files automatically update the
future LDP database.  Is this feasible?

> 
> WikiLearn is in place now.

My experience with wiki hasn't been too good.  In wikipedia, I corrected
some errors but someone restored these errors.

> 
> regards,
> Randy Kramer
			David Lawyer

Previous by date: 23 Nov 2003 18:19:54 -0000 Re: TLDP DocBook pages need work - Start there!, John R. Daily
Next by date: 23 Nov 2003 18:19:54 -0000 Re: TLDP DocBook pages need work - Start there!, John R. Daily
Previous in thread: 23 Nov 2003 18:19:54 -0000 Re: the good the bad and the ugly, David Lawyer
Next in thread: 23 Nov 2003 18:19:54 -0000 Re: the good the bad and the ugly, David Lawyer


  ©The Linux Documentation Project, 2014. Listserver maintained by dr Serge Victor on ibiblio.org servers. See current spam statz.