Subject:
Re: Linux documentation wiki
From:
David Merrill ####@####.####
Date:
13 Jan 2002 14:44:45 -0000
Message-Id: <20020113153614.GC25681@lupercalia.net>
On Sun, Jan 13, 2002 at 12:14:02AM -0800, David Lawyer wrote:
> On Sat, Jan 12, 2002 at 06:32:14PM -0500, David Merrill wrote:
> > That's not my thoughts. For one thing, the Wiki has a text database,
> > not html. I'd say:
> >
> > * Documents exist in a plain text format which is editable online.
> > That could be wiki or could be a simple edit box.
>
> Since linuxdoc-sgml is very readable, people could edit the linuxdoc-sgml
> text directly. A major problem is there would be no table of contents.
>
> > * Metadata would come from the database.
> > The other option is to include metadata tags in the text we support,
> > but that seems a lot harder to me than using what we already have.
> > Metadata changes infrequently so it doesn't seem important to make
> > it available for more general editing, like the rest of the text.
> > * Upon saving, the text files are processed by txt2db into docbook.
> > * The DocBook is then validated and published (on the wiki or database).
> The above two could be LinuxDoc
Yep, and that would be fine with me, but I think the text system I've
set up is even *easier* than LinuxDoc. Take a look at txt2db in the
cvs and see if you agree.
The benefit of using the text rather than linuxdoc, for one thing, is
that you can enter arbitrary docbook into it, as well as the
simplified text constructs. So despite it being a "text" system, you
can really make it arbitrarily complex if you wish. I don't think you
could do with if we went with linuxdoc, could we?
> > That's the editing part of it. Now the publishing stuff.
> >
> > * The DocBook is then reviewed using cvs diff, or plain diff if the
> > author doesn't have cvs.
>
> This is some work for the author. If the change doesn't need much
> editing, it's not hard. But if it needs extensive editing, it might be
> easier to use the existing methods of feedback where the authors put
> suggestions in their own words.
>
> The author needs to review the changes immediately, not weeks (or
> months) later. Plain diffs are hard to read. Do we have ones that are
> color-coded? Do they work with a command line interface?
We could put together an online review to make it easier, highlighting
changes and so on. A diff file is not that hard to parse and render in
red for deletions, blue for additions, etc.
> > * The approved changes are posted to cvs.
> > * Publication continues as normal from there.
>
> There will be a lot of authors that will not want to spend time doing it
> this way. It makes it easier on the author to use the currently used
> feedback scheme: The author gets email suggesting changes. There is
> more of person-to-person contact this way and sometimes an exchange of
> emails that produces a better result than just one person going ahead
> alone and making changes. The person-to-person contact results in sort
> of a productive bond between the two persons. The author feels an
> obligation to make the suggested changes and respond. The reader feels
> good about getting a favorable response (usually) from the author. If
> the suggestion is rejected, the author should explain why. If the wiki
> changes are not accepted, the changer may never know why.
We would not force authors to use it. It is their choice, if they find
it helpful. And, a place for us to start new HOWTOs on subjects we do
not yet cover, and solicit community help to build them. We could
either make the public domain, or hold copyright in one of our names
(or iBiblio's?). Somebody has to hold copyright if we GFDL it. I'd be
happy to just put it in my name, but perhaps someone has an objection
to that, doesn't trust me, whatever.
> But the wiki does entice readers to give feedback. It could help
> recruit new authors. However, we might encourage more conventional
> feedback to authors. Perhaps by encouraging more email links to the
> author in the documents. But putting such a link at the bottom of each
> page viewed would be going too far.
>
> People using wiki will want to use their own editor: vim, emacs, etc.
> Is this feasible? It worked for me on one site except that doing this
> gave me a text with paragraph and heading "tags" (markup symbols).
> I had to manually add these "tags" to what I wrote.
I don't know how that's possible.
> Another thing wrong with the wiki system is that there is less
> accountability. One can change a doc and not be responsible for the
> change. With a single-author doc, there is accountability since
> mistakes are the responsibility of the author. Thus persons editing a
> wiki doc may not use as much care in changing it as the author would.
Not necessarily. Some wikis require log on, and keep version
histories. We would want such a system, I think. I don't know about
totally promiscuous edits. I guess we could try it. I mean whatever we
start out with won't be carved in stone. If it doesn't work we can
change it. Nothing ventured, nothing gained.
> This might be corrected if the author carefully reviews what has been
> done. But this may not happen. In fact, if what is added is something
> the author knows little about, then it's not likely to happen. If it's
> an otherwise unmaintained doc, then there's also this problem.
Yeah, I understand your skepticism. There are things that can go
wrong, or badly. Only trying it will really find out, though.
I suspect this whole thing might work best for documents where there
is no official maintainer, and we have the LDP core cadre, who have
accounts, all able to accept/reject changes. The purpose of this whole
thing is to spread out the responsibility and the work, or at least
that's what I think is important about it. To get more people involved
in actively working on the documentation.
It might even be best of all for new documents, where nobody feels
"ownership" of the doc.
--
David C. Merrill http://www.lupercalia.net
Linux Documentation Project ####@####.####
Collection Editor & Coordinator http://www.linuxdoc.org
At the age of 12 I received my first scribe. At the age of 14, a Zoroastrian
named Wilma ritualistically shaved my testicles. There really is nothing
like a shorn scrotum. It's breathtaking; I suggest you try it.
-- Dr. Evil, Austin Powers: The Spy Who Shagged Me
