Hi, (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 contribute. 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 http://bitfluxeditor.org/. > [...] > 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 solution". 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. :) -- Gruß/Regards, Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX Products GmbH (o< Documentation Specialist Maxfeldstrasse 5 /\\ 90409 Nuernberg, Germany _\_v http://en.opensuse.org/Documentation_Team SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nürnberg) -- To unsubscribe, e-mail: opensuse-marketing+unsubscr...@opensuse.org For additional commands, e-mail: opensuse-marketing+h...@opensuse.org
