Subject:
Re: Linux documentation wiki
From:
David Merrill ####@####.####
Date:
15 Jan 2002 13:22:48 -0000
Message-Id: <20020115141413.GJ29019@lupercalia.net>
On Sun, Jan 13, 2002 at 04:01:06PM -0700, Charles Curley wrote:
> On Sun, Jan 13, 2002 at 11:58:58AM -0500, David Merrill wrote:
> > On Sun, Jan 13, 2002 at 08:18:30AM -0700, Charles Curley wrote:
> > > Would bugzilla be a better choice here?
> > >
> > > I've been watching the wiki discussion with some concerns, and haven't
> > > yet been satisfied. One of them is security, another is the integrity
> > > of the original document. Using bugzilla addresses both of those
> > > issues because it does not allow the bug filer access to the source.
> >
> > The whole point of a wiki, and the whole point of this exercise in the
> > first place, is to lower the barrier to entry. Anyone who is reading
> > the document and can make it better can do so easily and quickly
> > without any muss or fuss. I don't think Bugzilla would do that enough.
>
> Do we really want to lower the barrier to entry? I thought the point
> of LDP was to produce professional documentation. Not to be elitist,
> but I wonder if the barrier to entry isn't too low already? I refer to
> some of the atrocious grammar and spelling I've seen in released
> works. I can handle the occasional grammar or spelling glitch, but
> some of them obscure the meaning, and that's not acceptable.
>
> One response to that might be, "OK, Curley, you can use the wiki to
> make changes in grammar and spelling that offends you." Quite so. But
> I'd rather approach the maintainer first in private (so as not to
> embarrasss), and offer to make the edits, do so using my tools and the
> authoritative source, and send the maintainer a diff so that the
> maintainer can tell in detail exactly what I've done. And I can do
> that without a wiki.
>
> At one company, I was the only person using Emacs on the C source, so
> I was the only person with built-in spell-checking of strings and
> comments, which I used. Other developers complained to me that I had
> mangled their "correct" spelling. Given that experience, I prefer to
> approach people in private on that sort of thing.
I will not support making this something we force on authors. It will
be each author's choice whether to allow collaborative editing. Not
the LDP's!
Also, the choice as I propose it is fourfold:
1. the author only edits it, basically as things work now
2. registered users of the LDP database can also edit it
3. promiscuous editing by anyone
4. editing by selected registered users only (two authors or three,
perhaps all those already maintaining the howto)
Also, this would let us create new HOWTOs that are entire
collaborative if we want, with not real official maintainer other than
the LDP.
> > Keep in mind also that using a wiki would not have to give the poster
> > access to the "real" source. I would propose some kind of approval
> > mechanism, which could be by the author or an ldp volunteer, before
> > the changes are posted. We have not yet solved that though, but I
> > think we can.
> >
> > > Also, the wiki seems to require almost instantaneous response from a
> > > document's maintainer to a change. Bugzilla allows a more leisurely
> > > response because the change is not added to the original document in a
> > > manner that makes it appear to be part of the original document.
> >
> > Why would it require almost instantaneous response? The proposal is
> > that the wiki is updated immediately, but the core LDP cvs and website
> > is updated *whenever*.
>
> Because once a change is made to the wiki source, the next wiki user
> will get that source, not the real source in CVS. And will edit on the
> assumption that what is in the wiki is the correct and true version,
> which it isn't.
>
> Alternatively, the next user will get the original source, without the
> earlier proposed change. This could also cause problems. Again, bugzilla
> handles this problem: everyone posts to bugzilla working from the
> present source, knowing that other bug reports are pending.
Hmmmm. I'll have to think about that one. Surely we can come up with
something though.
Wikis usually provide a "view other revisions" capability, along with
a "diff between revision" function. We could provide those, as well as
a "view the cvs version" and "view diff with cvs" function.
> The whole point of CVS is to see to it that everyone is playing on the
> same page. If you update the wiki in near-real-time, but not the
> sources, then you have drift, and that's not acceptable.
>
> As near as I can tell, to avoid drift and move to wiki, we would have
> to abandon the present CVS system. I am flat out opposed to abandoning
> the CVS system, and in that event, I will withdraw from LDP work.
Not wholesale. The decision would be on a doc-by-doc basis, made by
the author.
> Another question: Does adding the wiki add to maintainers' work load?
> Are they now required to check the wiki from time to time for new
> input, or can the wiki be set up to email the maintainer when edits
> are made.
No, no, no. Never. Unless we can come up with a really easy way to
manage the "drift" we should ask the author to use the wiki only if he
does so exclusively.
> Going the other way, can we have the wiki advise users when the last
> update to the authoritative source was made so they can review that if
> necessary?
Absolutely.
> > It would be a good idea for everyone who is involved in this
> > discussion to try using Wikipedia or another wiki for awhile, so you
> > get a feel for how it works in practice. Or, see
> > http://www.wikipedia.com/wiki/Wikipedia/Our_Replies_to_Our_Critics
> > for their rebuttal to those kinds of criticisms. Wikis have their own
> > dynamic that is not really what you would expect if you haven't
> > actually spent some time on one. Wikis are nonintuitive. You really
> > have to actually use one for awhile to get the "wiki nature" as it's
> > called. :-)
>
> I may not get the chance to muck seriously with a wiki until next
> weekend. I did skim the Replies page, and found it useful, but
> sometimes a bit facile.
:-)
> > FWIW, the Wikipedia has written 20,000 articles in a single year, and
> > many of them are really, really excellent. The potentential is
> > astounding for the LDP if we could capture even a small percentage of
> > that dynamic.
> >
> > I agree with Charles that there are risks. Risks that it won't work,
> > that is. There is no risk to our documents in cvs if nothing goes
> > automatically into them. All we risk is our time and effort that might
> > be in a futile endeavor. I for one am willing to take that chance!
>
> I am perfectly willing to accept the risk that it won't work,
> especially as I have not volunteered to do any of the work to set up
> and test a trial system. :-) Seriously, I think it is worth testing,
> however skeptical I remain.
>
> My main concern is the integrity of the documents we now have, and
> ensuring that we have a process which maintains that integrity.
Good, thanks. Since you seem to have a very good grasp of the specific
technical and practical difficulties, you're helping whether you meant
to or not. Pointing out the problems to avoid is *very* helpful. ;-)
I am also very concerned about the same things.
--
David C. Merrill http://www.lupercalia.net
Linux Documentation Project ####@####.####
Collection Editor & Coordinator http://www.linuxdoc.org
Stop being paranoid. Gates is always whining about how any minute he can be
out of business because things change so fast in the software business. The
only companies put out of business in the software industry have been put
out either by their own incompetence or by Microsoft. Give it a rest. I'm
personally sick of listening to this one. In the early 1980s before
Microsoft was public, Gates would go on and on about how he could always
fall back on being a programmer if Microsoft went broke. Let's see, he's up
to $50 billion in net worth. When does this thinking end? At this point
it's pathological and unhealthy.
--John C. Dvorak, PC Magazine
