docbook to mediawiki

[Natas12]

Hallo,

ich arbeite an einem recht großen softwareprojekt mit, das seine dokumentation von grund auf "ordentlich" erstellen will. ich habe da an single source publishing mit docbook gedacht. als "targets" gibt es: html (onlinehilfe in webapplikation), pdf (druck) und wiki (mediawiki). und letzteres bereitet mir bauchschmerzen, da ich bisher kein "stylesheet" gefunden habe, das XML in mediawiki-code umwandelt (nur ein recht unzuverlässiges perl-skript, das im blender-forum herumflottiert). anders herum (wiki2docbook) geht es mittlerweile recht problemlos.

weiß jemand, ob es das gibt? gibt es einen docbook-experten, der sowas schon mal gemacht hat?

gruß

natas12

[ttyUSB0]

Ich würde als Ausgangsbasis ein Wiki verwenden. In einem größeren Softwareprojekt brauchen die Entwickler und auch Tester die Dokumentation sofort und immer überall. (Browser gibt es auf jeder Maschine).
Entwickler sind auch dokumentierfaul und wenn sie daß auch noch mit Aufwand betreiben müssen (in XML) dann läufst du immer hinterher.

[Natas12]

wir haben für die gegenwärtige version ein wiki mit sehr umfangreicher dokumentation. das problem ist, dass ohne "single source" ein extremer wildwuchs entstanden ist und wir berfürchten, dass dies - trotz eines styleguides - auch bei der neuen version der fall sein wird. das wiki hat noch weitere probleme:

(1) es lässt sich schwer durchsuchen (die mediawiki-suche ist ungeeignet)
(2) es lädt zu schnellen ad-hoc änderungen ein und verhindert die durchsetzung eines stilleitfadens und einer echten redaktionellen arbeit
(3) es lässt sich aus einzelnen miteinander verlinkten artikeln kaum ein handbuch erstellen

letzteres wird von kunden jedoch verlangt (oder zumindest die möglichkeit, sich ein pdf auszudrucken). moderne dokumentationsparadigmen lassen sich zudem schwer mit wiki abbilden: re-use, one source - multiple targets usw. ich spreche hier von dokumentation im bereich mehrerer tausend seiten (benutzer- und technische dok.)!

wiki soll als plattform erhalten werden, es wäre aber imho ein "sauberer" workflow, wenn es eine xml-quelle gäbe, die dann in unterschiedliche ausgabeformate transformiert wird. da sich die entsprechenden entwickler ohnehin mit eclipse und xml befassen, müssten sie noch nicht mal "umlernen"...

[duese]

Ich habe [1] gefunden. Auf der Seite sind auch weiterführende Links. Gefunden habe ich das über eine Suche per [2], vielleicht sind da noch interessantere Dinge dabei. Vielleicht ist [3] auch interessant.

Gruß,
Thomas

[1]: http://www.mediawiki.org/wiki/DocBook_XML_export
[2]: http://www.mediawiki.org/wiki/Special:S ... book&go=Go
[3]: http://www.mediawiki.org/wiki/Extension:XML_Bridge

[duese]

(1) es lässt sich schwer durchsuchen (die mediawiki-suche ist ungeeignet)

Kenn ich. Je nachdem, welche Mediawiki-Version ihr verwendet, hilft die Lucene-SearchEngine euch weiter. Siehe [1] und [2].

(2) es lädt zu schnellen ad-hoc änderungen ein und verhindert die durchsetzung eines stilleitfadens und einer echten redaktionellen arbeit
(3) es lässt sich aus einzelnen miteinander verlinkten artikeln kaum ein handbuch erstellen

Es liegt in der Natur eines Wikis schnelle ad-hoc-Änderungen durchführen zu können. Eventuell solltet ihr euch näher mit den Strukturelementen von Mediawiki auseinandersetzen. Beispielsweise Namensräume, Kategorien, ...
Eigene Namensräume kann ich nur empfehlen. Z.B. Namensraum "Programmcode" für alle Programmlistings. Man kann dann in der Suchmaske alle Programmcodes ausblenden, wenn dies gewünscht wird.

Eventuell würde ich mir auch die Prinzipien von Wikibooks anschauen. Dort werden ja kollaborativ "Bücher" erstellt.

Gruß,
Thomas

[1]: http://www.mediawiki.org/wiki/Extension:Lucene-search
[2]: http://www.mediawiki.org/wiki/Extension:LuceneSearch

[Natas12]

danke für die infos.

namensräume und kategorien nutzen wir bereits intensiv, allerdings sind unsere schreiberlinge manchmal kategorienfaul oder wiederum zu kategorienfreundlich. es ist zum mäusemelken mit der doku...

neue suchmaschine klingt aber gut, ich weiß gar nicht, was wir genau einsetzen (nicht mein gebiet), da werde ich mal nachhaken...

[duese]

[...]anders herum (wiki2docbook) geht es mittlerweile recht problemlos.[...]

Du schreibst, von wiki nach docbook sei problemlos. Was verwendest Du als Wikisoftware, was um aus dem Wiki heraus zu exportieren? Ich frage, weil ich mich auch gerade in DocBook einarbeite.

Gruß,
Thomas