Mailinglist Archive: opensuse-doc (21 mails)

< Previous Next >
[opensuse-doc] Re: [opensuse-marketing] The openSUSE Handbook proposal
  • From: Thomas Schraitle <toms@xxxxxxx>
  • Date: Mon, 4 Oct 2010 08:44:02 +0200
  • Message-id: <201010040844.02805.toms@xxxxxxx>

(CC'ed opensuse-doc so doc people can read that too.)

On Monday 04 October 2010 Christian Boltz wrote:

I'm not sure about that. I don't say that it will be very easy, but it
should be possible, and it won't be too hard.

You are underestimate the efforts.

90% of the formatting can be done with plain wikitext, and for the
remaining 10% templates can be used (which can, but don't have to have a
visible effect in the wiki). A "visible" template might be something
like "text printed on screen", an "invisible" template might contain a
keyword for the book index.

We use a feature in DocBook/Novdoc what is called "profiling". We label one
paragraph for business related products and another one for openSUSE products.
When we process the manual, the paragraphs are being "filtered" so only the
requested product is visible in the end format. Maybe this belongs to the
remaining 10%...

I think we could even develop a "XML skin" for mediawiki so that the
wiki can generate valid docbook/novdoc XML out of wiki pages (with
<para> instead of <p> etc.).
The alternative solution would be to post-process the wikitext or the
HTML to convert it to XML.

Depending on the HTML this sounds scaring.

Basically the two methods don't differ too
much, the main difference/question is if you want XML output integrated
in the wiki or not.

I would propose XML hosted on SVN. Although the learning curve would
be a bit stepper than with e.g. wiki markup it would give us the
maximum flexibilty and a guaranteed future.

I'm afraid that the learning curve is too high - lessons for lizards
unfortunately gave you/us that lesson...

Sorry, but I never understood the "XML is too difficult" rant. People are
*not* afraid to learn LaTeX or Wiki, dig into HTML, or even migrate from
Windows to Linux because of "the learning curve is too high". Why they are not
afraid? Because they are _interested_ and want to _learn_ something new.

Why should it be difficult to learn DocBook/Novdoc? It's just a format as
HTML, WikiText, ASCIIDoc, or anything else. Maybe it's a bit more verbose, but
if you can write HTML and design your webpage, you can also write
documentation in DocBook or Novdoc. It's just a matter of your XML editor.

Of course, Lessons for Lizards was not as successful as we wished it would be.
However, it's a bit too easy to blame only XML for the demise. Maybe it had an
effect, maybe not. The biggest problem IMHO was time and marketing.

I don't know if the learning curve was the only problem there, but at
least it's "I have to learn another thing before I can contribute".

I'm afraid, I have to disagree here. "To learn another thing before I can
contribute" is the case for _every_ open source project. If you want to
contribute, you usually use what's there. If you are interested enough then
you are willing to take that "extra step". If not, you simply don't

Just think of this example: People were not afraid to learn CVS. After some
time, it was more or less replaced by Subversion. Although it was not that
different, people were willing to learn the differences. Now it seems Git will
be the sucessor for Subversion. And *that* is really different from
CVS/Subversion! And what's the opinion? "Git is soo coool!" is what can I
heare a lot. ;)

Whatsmore, the existing documentation (speaking of almost
2000 pages!!) already uses XML.

OK, _that_ is an argument. But as you already wrote, it shouldn't be
hard to convert it to wikitext.

Indeed, there are stylesheets (I've wrote it), but I wouldn't want to
transform a complete book. The two systems are too different in some aspects.

And it would be a good testbed for the
wikitext to XML converter - ideally there should be no difference after
converting it forth and back again ;-) (and that would make us better
than google translator *g*)


Let me suggest another idea:
In my opinion, most people have problems with XML because it's (a) too
verbose, (b) it's too "complicated", and (c) you don't see the result. At
least that's what I hear a lot.

As most of the functionality thesedays goes through the Web, why not have a
XML editor in, let's say, Firefox?

Of course, it should offer the usual features but would hide the XML syntax
and display just the rendered text. I know, this is day-dreaming and the idea
is not new. However, I think, this would lower the entrance. We could use the
existing XML source without converting it to Wiki while embracing Web
usability. I think, this should solve the above problems.

Maybe we could use Bitflux, see

I see the public SVN as a fast solution so that people have a chance to
dig into the manual's source. It might even be read-only in the
beginning - having to upload patches to bugzilla or send them to the
-doc mailinglist is still easier than reporting "on page 123 in section
'foo', there's a typo in 'baar'".

A page number is a bad choice as it can change easily. Better use the section
title or an anchor from HTML. :)

But even if you give out SVN write access, I'm afraid that not many
people will contribute to the XML source because of the learning curve.

What makes you so sure?

To cite Tim Berners-Lee:
»If you use the original World Wide Web program, you never see a URL or have
to deal with HTML. That was a surprise to me - that people were prepared to
painstakingly write HTML.«

You have to "switch" from the rendered manual (HTML, PDF, ...) to the
XML source, and you have to know at least some XML basics.

In Wikis you have to know some Wiki basics. What's the point here? :)

OTOH the wiki is more like a long(er)-term solution, but makes
contribution much easier - just click "Edit".

Sorry, I'm not convienced. DocBook exists for more than 10 years! It's well-
matured, very well documented, and it's one defacto standard for technical
documentation. Ok, maybe you can count DITA as well.

Although I'm not that much into the Wiki topic, I have the impression the Wiki
syntax is not very well "established": One Wiki supports a certain syntax,
another don't. If this is really the case, I wouldn't call Wikis "a long-term

For easier contribution: See my idea above.

Yes, writing a good wiki-to-XML tool will need some work, but it is
possible. And it is worth the effort IMHO.

Why should we write some wiki-to-XML converter when we have already everything
in place, ready to be used?


You've seen the numbers from Rajko - around 90 active users in the last
3 months. That's still 89 more than in the "lessons for lizards" *g,d&r*

You compare apples with oranges. :)

Thomas Schraitle

SUSE LINUX Products GmbH (o< Documentation Specialist
Maxfeldstrasse 5 /\\
90409 Nuernberg, Germany _\_v
SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nürnberg)
To unsubscribe, e-mail: opensuse-doc+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-doc+help@xxxxxxxxxxxx

< Previous Next >