Subject:
Re: the good the bad and the ugly
From:
Randy Kramer ####@####.####
Date:
20 Nov 2003 12:48:32 -0000
Message-Id: <200311200800.10398.rhkramer@fast.net>
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.
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.)
> 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).
> 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.
Many readers may send him the same comment because they don't know that
someone else has mentioned a problem.
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
* answer questions raised (explicitly or implicitly) for the author or
other readers
Further, when the author goes to modify the document, the wiki provides a
single source for many of the comments.
> > 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?
WikiLearn is in place now.
regards,
Randy Kramer
