Mailinglist Archive: opensuse-doc (120 mails)

< Previous Next >
Re: [opensuse-doc] Wiki to PDF? Using Wiki as a doc source?
  • From: Clayton <smaug42@xxxxxxxxx>
  • Date: Fri, 27 Apr 2007 09:34:40 +0200
  • Message-id: <e29967880704270034r5ee75323ib43121b573307aa@xxxxxxxxxxxxxx>
I'd rather vote to enhance the wiki to make it accept DocBook XML as an
input format.

While this would make live easier for generating output formats, it
doesn't really do much for the end user who is simply looking for a
quick and dirty way to contribute to an open source project... does
it?  The entry threshold for editing XML isn't unreachably high, but
it is inconvenient, and enough to stop a whole lot of people from
adding their knowledge to the documentation.

I see it all the time with the stuff I work on... and it's really not
a lot different here in L4L (they have to add a repository, check out
the docs from svn, edit them locally in some xml editor, validate and
check them all back in) from OpenOffice. (they have to create a child
workspace, check out the documentation, edit the xml in some xml
editor, validate and check it all back in again).

Those who work with it all the time don't think twice about it.... a
new users sees the "Quick Start" process... and don't bother.  How
much community input is there in the official openSUSE docs... or in
the L4L project... or in OpenOffice.  There is some in each case, but
not much.

The advantage of Wiki format for input is that the syntax is simple -
or if you have Javascript, you don't even need to know Wiki syntax...
just click the buttons above the edit window.  It's quick, and you can
edit on the fly (ok, potential for content abuse, but that's a risk
I'm willing to manage).

Maybe I'm missing the point though :-)  It's been known to happen more
than once with me.

The mediawiki file format is rich enough for computer related books.

I would agree - for the most part, all the testing I've done with
porting an existing book to Wiki format has gone quite good... getting
it back out has been the issue (and why I started this thread).  The
end users (from developers who need to write content to end users who
want to add little extra bits) are all quite interested in seeing the
book migrate from it's difficult to manage existing process onto the

The only other thing I've been struggling with is the total lack of
linear navigation in Wikis. I think I've found one solution that seems
to work nicely.  I've hacked up a description of it here:
It allows for simple guided navigation (in this case, in a box on the
RH side of every page) using block and none to show and hide sections.

I'm still working on various ideas for extracting Wiki to XML.

To unsubscribe, e-mail: opensuse-doc+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-doc+help@xxxxxxxxxxxx

< Previous Next >
Follow Ups