Dokumentation mit DocBook

Dokumentation mit DocBook

Posts 1-10 of 11
  • Alexander von Hedenström
    Alexander von Hedenström    Premium Member   Group moderator
    The company name is only visible to registered members.
    Was geht mit DocBook? Alternativen?
    Guten Tag!

    Für unsere Software suchen wir eine Möglichkeit, Dokumentationen möglichst einfach zu verfassen und anschliessend in die benötigten Ausgabeformate zu bringen. Diese sind vor allem PDF und HTML. Dabei bin ich auf verschiedene Produkte gestossen, vor allem DocBook und RoboHelp. Ich bin mir allerdings noch nicht sicher, ob unsere Anforderungen erfüllt werden können:

    1. Unser Marketing hat ziemlich hohe Ansprüche an das Design, auch für die Dokumentation. Prinzipiell erscheint es verlockend, dieses in abstrakter Form zu erstellen und anschliessend die Inhalte damit zu rendern.

    2. Für die Online-Hilfe der Programme werden nicht das gesamte Handbuch, sondern nur Kurzreferenz und Glossar benötigt. Beide sollen in entsprechend kleine Stücke in HTML vorliegen und können so zu einzelnen Themen angezeigt werden.

    Ich habe aber bisher keine Beispiele gefunden, die wirklich ansprechend gestaltet waren, an denen man sich diese Verfahren abgucken könnte, und habe so meine Zweifel, ob es a) funktioniert, b) sich mit realistischem Aufwand umsetzen lässt.

    Haben Sie Erfahrungen mich DocBook, RoboHelp oder anderen Produkten gemacht?
    Kennen Sie gute, aufwendige Beispiele oder umfassende Tutorials?

    Vielen Dank!
    • 06 May 2005, 1:25 pm
  • Lars Trieloff
    Lars Trieloff
    The company name is only visible to registered members.
    Re: Was geht mit DocBook? Alternativen?
    Hallo,

    Zu RoboHelp kann ich leider keine Aussage machen, aber die Vetriebsmitarbeiter von Macromedia werden Ihnen sicherlich weiterhelfen können.

    Ihre Anforderungen, PDF und HTML aus einer Quelle zu erzeugen kann DocBook erfüllen. Da semantisches Markup genutzt wird, sind auch andere Ausgabeformate denkbar.

     
    1. Unser Marketing hat ziemlich hohe Ansprüche an das Design, auch für die Dokumentation. Prinzipiell erscheint es verlockend, dieses in abstrakter Form zu erstellen und anschliessend die Inhalte damit zu rendern.
    Wenn die Ansprüche an das Design, insbesondere bei gedruckter Dokumentation extrem hoch sind, können automatische Verarbeitungen in der Regel kein zufriedenstellendes Ergebnis liefern.

    Allerdings kann DocBook auch von Desktop Publishing Programmen wie Framemaker eingelesen werden, so dass ein Layout-Experte die gewünschen Formatierungsregeln festlegen kann und abschließend noch Feintuning vornimmt.

     
    2. Für die Online-Hilfe der Programme werden nicht das gesamte Handbuch, sondern nur Kurzreferenz und Glossar benötigt. Beide sollen in entsprechend kleine Stücke in HTML vorliegen und können so zu einzelnen Themen angezeigt werden.
    Dies lässt sich mit verhältnismäßig wenig Aufwand erledigen. Wenn Sie wünschen, dass jeder Glossareintrag zu einer einzelnen HTML-Seite wird, ist es angebracht, den Aufspaltungs-Mechanismus der DocBook-XSL-Stylesheets anzupassen, da sonst die erzeugten HTML-Fragmente das komplette Glossar enthalten.

    viele Grüße

    Lars Trieloff
    • 06 May 2005, 8:41 pm
  • Alexander von Hedenström
    Alexander von Hedenström    Premium Member   Group moderator
    The company name is only visible to registered members.
    Gute, umfassende Beispiele?
    1. Unser Marketing hat ziemlich hohe Ansprüche an das Design, auch
    für die Dokumentation. Prinzipiell erscheint es verlockend, dieses in
    abstrakter Form zu erstellen und anschliessend die Inhalte damit zu
    rendern.
    Wenn die Ansprüche an das Design, insbesondere bei gedruckter
    Dokumentation extrem hoch sind, können automatische Verarbeitungen in
    der Regel kein zufriedenstellendes Ergebnis liefern.
    Tja, das ist genau meine Befürchtung! Auch wenn ich nicht, zumindest nicht für den Bereich Dokumentation, von extrem hohen Ansprüchen sprechen würde. Trotzdem würde ich ja gern mal ein wirklich gutes Beispiel sehen - insbesondere um die Kollegen überzeugen zu können. Im Internet finde ich nur die typischen Hallo-Welt-Beispiele. Die zeigen das es funktioniert, sagen aber leider nichts über die Praxistauglichkeit aus....

    Besonders unter dem XSLT, welches dann aus XML das fertig gestaltete PDF machen soll, kann ich mir derzeit wenig vorstellen.

    Ich werde nochmal weiter suchen. Bin für alle Vorschläge dankbar!
    This post was modified on 07 May 2005 at 11:10 am.
    • 07 May 2005, 11:06 am
  • Lars Trieloff
    Lars Trieloff
    The company name is only visible to registered members.
    Re: Gute, umfassende Beispiele?
    Tja, das ist genau meine Befürchtung! Auch wenn ich nicht, zumindest nicht für den Bereich Dokumentation, von extrem hohen Ansprüchen sprechen würde.
    Damit meinte ich Dinge wie individuell formatierte Bilder und Textabschnitte. Alles was man mit Formatvorlagen von Textverarbeitungsprogrammen erreichen kann, kann durch die bestehenden Toolchains ohne weiteres abgedeckt werden.

    Trotzdem würde ich ja gern mal ein wirklich gutes Beispiel sehen - insbesondere um die Kollegen überzeugen zu können. Im Internet finde ich nur die typischen Hallo-Welt-Beispiele. Die zeigen das es funktioniert, sagen aber leider nichts über die Praxistauglichkeit aus....
     
    Wenn Sie Interesse haben, kann ich Ihnen einige Beispieldokumente für Anpassungen der Stylesheets zusenden, die über Hello-World hinausgehen.
    • 08 May 2005, 9:46 pm
  • Alexander von Hedenström
    Alexander von Hedenström    Premium Member   Group moderator
    The company name is only visible to registered members.
    Re^2: Gute, umfassende Beispiele?
    Tja, das ist genau meine Befürchtung! Auch wenn ich nicht, zumindest nicht für den Bereich Dokumentation, von extrem hohen Ansprüchen sprechen würde.
    Damit meinte ich Dinge wie individuell formatierte Bilder und Textabschnitte. Alles was man mit Formatvorlagen von Textverarbeitungsprogrammen erreichen kann, kann durch die bestehenden Toolchains ohne weiteres abgedeckt werden.     Ich habe bisher immer versucht, alle Formatierungen über solche Formatvorlagen zu realisieren. Mit dem aktuellen Word bin ich damit auch ausgekommen.

    Wenn Sie Interesse haben, kann ich Ihnen einige Beispieldokumente für Anpassungen der Stylesheets zusenden, die über Hello-World hinausgehen. Das wäre natürlich sehr freundlich!
    • 09 May 2005, 08:39 am
  • Siegfried Göschl
    Siegfried Göschl    Premium Member
    The company name is only visible to registered members.
    Re^3: Gute, umfassende Beispiele?
    Einige Beispiel, welches ein wenig über "Hello World" hinausgehen ..

    +) das Subversion Buch - siehe http://svnbook.red-bean.com/.
    +) http://maven-plugins.sourceforge.net/maven-sdocbook-plugin/i...
    +) Basierend auf den Vorlagen des Subversion Buches schreibt die Canoo WebTest Community gerade ein Buch, wobei HTML und PDF via Maven generiert wird - siehe https://svn.canoo.com/trunk/webtest-book


    Cheers,

    Siegfried Goeschl
    • 09 May 2005, 10:42 am
  • Torge Wellßow
    Torge Wellßow
    The company name is only visible to registered members.
    Re: Was geht mit DocBook? Alternativen?
    Hallo, Herr von Hedenström,

    wir, bei Frametexx, erstellen die Produktdokumentation unserer Softwareentwicklungen seit geraumer Zeit auf Basis von DocBook und sind bisher mit den Gestaltungsmöglichkeiten, die DocBook und XSL bietet, sehr zufrieden. Mit etwas XSL-Programmierung für die Templates kommt man schnell zum gewünschten Ergebnis.

    Die Frage ist natürlich, was Ihre Marktingabteilung genau unter einem hochwertigen Design versteht?

    Wir haben für unsere Zwecke die Standard-XSL-Templates wie folgt angepaßt:
    - Kopfzeilen mit den jeweiligen Firmen- und Produkt-Logos
    - Fußzeilen enthalten den Namen des jeweiligen Kapitels
    - Hintergrundfarben für Tabellen (Überschriften und normale Zellen)
    ensprechend zu den Produktfarben
    - Gesonderte Templates zum Unterdrücken von:
    Titelseite,
    Inhaltsangaben oder
    Revisionsübersicht
    - Textfarbe rot zusätzlich zu fett und kursiv

    Um die Dokumente klein zu halten, legen wir einzelne Abschnitte/Kapitel in getrennten Dokumenten an, und können so auch Teile der Dokumentation als HTML-Seite für die Online-Hilfe anbieten.

    Um die Möglichkeiten von DocBook unternehmensweit nutzen zu können stellt sich jedoch schnell die Frage nach einem Editor, der dem technisch (XML/XSL) nicht so versierten Mitarbeiter alle (notwendigen) Möglichkeiten von DocBook an die Hand gibt, ohne daß er erst DocBook-Tags lernen muß oder den Umgang mit Tools zur Konvertierung nach HTML oder PDF.

    Aus diesen Überlegungen ist in unserem Hause das Produkt "Framebook Documentation Manager - revision-safe documentation" entstanden, das inzwischen auch bei einem unserer Kunden aktiv genutzt wird.

    Die Dokumentation ist webbasiert und erfolgt gesichert über HTTPS. Wir gestalten darüber nicht mehr nur die Dokumentation unserer Softwareprodukte, sondern begleiten damit auch die Phasen Anaylse, Design und Spezifikation und können hier zur besseren Abstimmung den Kunden mit einbeziehen. Auch die gemeinsame Ausgestaltung von Vertragswerken ist ein neues Anwendungsgebiet.

    Das Dokument durchläuft im Entstehungsprozess die Phasen "Edit", "Review" und "Publish" und unterstützt
    damit in hervorragender Weise die teamorientierte Arbeit aber auch die Qualitätssicherung am Dokument. Durch Festlegung von Berechtigungen lassen sich die Rollen eines Benutzers im Projekt festlegen. Nicht jeder hat auf alles Zugriff. Nicht jeder darf Dokumente editieren, korrekturlesen oder veröffentlichen.

    Hinzu kommt, daß alle wir alle Änderungen am Dokument gesondert ablegen. So kann, gerade im Fall von Spezifikationen, jederzeit nachgewiesen werden, Wer-Wann-Welche Änderungen eingebracht hat. Auch läßt sich jederzeit auf einen alten Versionsstand zurückgehen.

    Einmal klein angefangen unterstützt Framebook inzwischen immer mehr DocBook-Tags, ohne daß der Anwender auf den Komfort einer "Textverarbeitung" verzichten muß:

    - Kapitel, Unterkapitel, Inhaltsverzeichnis
    - Paragraphen, Programm-Listings
    - Bilder (inkl. Ausrichtung und Größe)
    - Listen (geordnet und ungeordnet, geschachtelt)
    - Tabellen (inkl. Column-Span, Ausrichtung, Bildern und Listen)

    Mittels Referenzen auf Dokumente können einzelne Kapitel im Produkt zusammengelinkt werden, um so eine "Gesamt-Dokumentation" zu erstellen.

    Das Design des Outputs ist nach wie vor über verschiedene XSL-Stylesheets vorgegeben und anpaßbar. Um die Dokumente im Unternehmen einheitlich zu gestalten, geben wir Stylesheets vor und der Anwender kann sich das passende aus den Vorgaben aussuchen.

    Ein Glossar verwenden wir bisher noch nicht, ist aber durchaus denkbar. Derzeit implementieren wir die Verwendung von Index und Appendix.

    Falls ich Ihr Interesse geweckt habe, können Sie mich gerne direkt kontaktieren.

    mit freundlichen Grüßen,

    Torge Wellßow (FrameTexx GmbH, Hamburg)
    • 13 May 2005, 12:41 pm
  • Arno Sosna
    Arno Sosna
    The company name is only visible to registered members.
    Re: Was geht mit DocBook? Alternativen?
    Alexander von Hedenström schrieb am 06/05/2005, 1:25 pm:
    Guten Tag!
     
    Für unsere Software suchen wir eine Möglichkeit, Dokumentationen möglichst einfach zu verfassen und anschliessend in die benötigten Ausgabeformate zu bringen. Diese sind vor allem PDF und HTML. Dabei bin ich auf verschiedene Produkte gestossen, vor allem DocBook und RoboHelp. Ich bin mir allerdings noch nicht sicher, ob unsere Anforderungen erfüllt werden können:
    DocBook wurde genau dafür entwickelt. Da es eine XM-Sprache ist, lässt es sich verhältnismäßig einfach in andere Formate umwandeln. HTML für Web, XSL-FO für Print sind da wohl die wichtigsten. XSL-FO zu PDF ist dann kein Problem da hier bereits komplette Lösungen vorliegen (open-source bis kommerziell). Der absolute Vorteil liegt in der Trennung von Layout und Inhalten. Neue Formate können sehr einfach angesteuert werden, man ist hier an keinen Hersteller gebunden.

    1. Unser Marketing hat ziemlich hohe Ansprüche an das Design, auch für die Dokumentation. Prinzipiell erscheint es verlockend, dieses in abstrakter Form zu erstellen und anschliessend die Inhalte damit zu rendern.
    DocBook verlang hier einen mehrstufigen, professionellen Prozess. Layout durch einen Grafiker, dann Umsetzung in XSLT-Stylesheets. Programme wie Quark oder Framemaker sind hier sehr angesehen. Die Stylesheets können manuell oder mit Hilfe (teurer) Tools erstellt werden.

    Das Schöne ist, das alle alten Inhalte in DocBook dann als Grundlage für zb Flyer im neuen Design herangezogen werden können. Wieder die Trennung von Inhalt und Layout.

    2. Für die Online-Hilfe der Programme werden nicht das gesamte Handbuch, sondern nur Kurzreferenz und Glossar benötigt. Beide sollen in entsprechend kleine Stücke in HTML vorliegen und können so zu einzelnen Themen angezeigt werden.
    Modularität ist in DocBook sehr einfach zu realisieren. Hier werden wieder die Stärken von XML sichtbar. Indizes und TOC werden von den DocBook Standard-XSLT-Stylesheets bereits komplett automatisiert erzeugt.

    Generell ist XML hier das perfekte Format, da es bereits jetzt eine Unmenge an Tools gibt, die alle Prozesse rund um XML unterstützen. Open-Source, Freeware oder kommerziell. Sie haben die Wahl und sind an keinen Hersteller gebunden.

    Besonders interessant wird DocBook in Verbindung mit SVG, einer weiteren XM-Sprache zur Beschreibung von Vektorgrafiken. Sie können also die reinen Inhalte zb eines Balkendiagramms in ihrem DocBook Dokument ablegen und dann über Stylesheets das Aussehen dieser Grafiken steuern.

    Nachteil von DocBook ist definitv das Erstellen der Dokumente. Wollen Sie die Stärken von DocBook wirklich nutzen, so sollte man direkt in DocBook schreiben. Hier empfiehlt sich aus meiner Sicht der XML Spy von Altova, der XML in einer eigenen grafischen Sicht präsentiert (grid view). WYSIWIG-Oberflächen nehmen für die Authoren Komplexität raus, allerdings geht einfach viel Information verloren, die in DocBook Tags ausgedrückt werden könnte.

    wbr,
    Arno Sosna
    • 13 May 2005, 1:10 pm
  • Gunthilde Sohn
    Gunthilde Sohn    Premium Member
    The company name is only visible to registered members.
    Re: Was geht mit DocBook? Alternativen?
    Hallo Herr von Hedenström,
    wir haben bereits einige Erfahrungen im internationalen Konzernumfeld mit XML basierten Hilfe- und Dokumentationssystemen gemacht. Wir setzen dazu ein XML-fähiges CMS ein. Die Texte werden zentral hinterlegt und können je nach Anforderung als Onlinehilfe (z.B. kontextsensitiv aus der Anwendung heraus oder komplett als Printdatei ausgepielt werden.)

    Für Detailfragen hierzu kann kontaktieren Sie am besten Herrn Michael Claas, F1 Easy GmbH: michael.claas@f1-easy.de

    Viele Grüße,
    Gunthilde Sohn, instinctools GmbH
    • 04 Jul 2005, 4:05 pm
  • Ariane Anders
    Ariane Anders    Premium Member
    The company name is only visible to registered members.
    Re: Was geht mit DocBook? Alternativen?
    Guten Tag, Alexander von Hedenström,

    Für unsere Software suchen wir eine Möglichkeit, Dokumentationen möglichst einfach zu verfassen und anschliessend in die benötigten Ausgabeformate zu bringen. Diese sind vor allem PDF und HTML. Eine andere Alternative ist AuthorIT. Das ist ein Single Source Publishing System. Die Software wurde von einem technischen Autor konzipiert und das merkt man ihr an.
    Einmal eingerichtet, ist der Dokumentationsprozess standardisiert. Inhalte können wieder verwendet werden. Verwaltung von Bild und Text ist möglich. Inhalte können in "Bücher" unterschiedlich zusammengestellt werden. AuthorIT ist bei der Generierung so "intelligent", dass nur Links zu enthaltenen Inhalten erzeugt werden, es gibt also keine "broken links".

    Sie haben die Auswahl folgender Ausgabeformate
    chm, hlp, doc, javahelp, html, oracelhelp, xhtml
    In Planung ist die neue Longhornhelp.

    Über das doc-Format (Word) können Sie dann das PDF produzieren. Einer meiner Kunden legt ebenfalls Wert auf ein hochwertiges Layout. Er ist mit dem Ergebnis aus Word => PDF zufrieden. Das Handbuch wird mit einer Schmuckfarbe gedruckt. Die Druckerei kann das Dokument direkt verarbeiten.

    Übrigens vertreibe ich das Autorensystem nicht, sondern bin nur eine begeisterte Anwenderin davon. Eine der ersten in Deutschland übrigens.

    Eine Stärken von AuthorIT ist auch die Importmöglichkeit. Sie können vorhandene Worddokument, HTML-Datei und auch Framemakerdateien importieren. Es ist möglich Importregeln aufzustellen, damit werden den Texten schon Formatvorlagen zugewiesen. Sie müssen hier also nicht mit copy and paste Texte übernehmen.

    Informationen zu AuthorIT finden Sie hier:
    http://authorit.com (Seite vom Hersteller)
    http://authorit.de (Seite von deutschen Vertriebspartner)

    Sollten Sie noch Fragen haben können Sie mich gerne per privater Mail kontaktieren.

    Herzliche Grüße aus Heidelberg
    Ariane Anders
    • 13 Jul 2005, 11:46 am