Mein Team verwendet MadCap Flare, um eine große Menge an Dokumentationen (Tausende von Themen) zu erstellen. Die Quelle ist „Flare HTML“, HTML mit einigen Flare-Ergänzungen (für Variablen, Ermahnungen, Schnipsel usw.). Wir verwenden CSS, um den HTML-Code nach unserem Geschmack zu gestalten. Wir verwenden das Build-Tool, das mit Flare geliefert wird, um die Ausgabe zu erzeugen, die von Skripten gesteuert wird, die eine gewisse Vorverarbeitung durchführen (wie z. B. sicherzustellen, dass Inhaltsverzeichniseinträge aktualisiert werden, wenn sich Themenüberschriften ändern).
Wir würden statt reinem HTML lieber eine semantische Auszeichnungssprache wie DocBook XML oder DITA XML verwenden. Semantisches Markup würde eine Reihe von Schreibproblemen für uns lösen. Aber wir haben in Flare keine Möglichkeit gefunden, dies zu tun, und unsere Autoren sind sehr an das Tool gebunden und arbeiten fast ausschließlich direkt mit der Flare-GUI. Einige unserer Benutzer verfügen über Flare-Kenntnisse auf Expertenniveau; Aus diesem und anderen Gründen wäre ein Werkzeugwechsel sehr schwierig.
Gibt es eine Möglichkeit, Flare mit einer semantischen Auszeichnungssprache zu verwenden und dabei die Vorteile der Verwendung der Flare-GUI zu bewahren, damit die Erfahrung für unsere Autoren ungefähr dieselbe ist wie jetzt? HTML ist in Flare „eingebacken“; können wir stattdessen in DocBook oder DITA backen? (Das Backen in einer kleinen Teilmenge der DocBook-Spezifikation wäre in Ordnung; als ich DocBook verwendet habe, habe ich wahrscheinlich nur 20-25 der 400 Elemente im Schema verwendet. Ich bin mit DITA weniger vertraut.)
Ich nehme an, dass wir für den Build einen Transformationsschritt hinzufügen müssten, um das semantische Markup in HTML umzuwandeln, bevor es dem Flare-Build zugeführt wird. (Das scheint sowieso einfacher zu sein, als den Flare-Build dazu zu bringen, ein anderes Schema zu verstehen.) Das ist praktikabel (wir schreiben diesen Build sowieso), obwohl Verbesserungen daran willkommen wären.
Unsere primäre Ausgabe ist HTML, aber wir produzieren auch PDF, wo die Formatierung manchmal etwas chaotisch endet. Wir können das PDF noch nicht vollständig über Bord werfen, daher muss eine Lösung für dieses Problem auch PDF berücksichtigen. Unsere HTML-Anforderung lautet „sieht gut aus“ und unsere PDF-Anforderung lautet „geht nicht kaputt“.
1 Sonstige Gründe: (a) kein Budget; (b) dies ist das bevorzugte Unternehmensinstrument (also die Politik); (c) Dieses Team hat bereits einmal Tools geändert, vor ungefähr 3-4 Jahren, glaube ich, und hin und wieder stoßen wir immer noch auf suboptimale Artefakte dieser Änderung.
DITA ist eine der Ausgabeoptionen für Flare. Sie können ein neues DITA-Ziel direkt neben beliebigen HTML- oder PDF-Zielen erstellen. Wir verwenden es nicht in meiner Firma, aber ich habe ein bisschen damit gespielt, um zu sehen, wie es funktioniert.
Ich bin mir nicht sicher, wie umfassend die DITA-Struktur unterstützt wird. In meinen kurzen Experimenten habe ich gesehen, dass die Schlüsselwörter von madcap in der DITA-Ausgabe in indexterm- Element -Tags übersetzt werden . Variablen werden in ph - Element-Tags mit conref- Attributen in der DITA-Ausgabe eingeschlossen, und eine mcvars.dita-Datei ist im Ressourcenordner der Ausgabe enthalten. Diese Datei listet nur die Variablen auf, die in der Flare Target-Datei für die DITA-Ausgabe ausgewählt wurden.
Zur Veranschaulichung ist dies ein kleines Beispiel für die DITA-Ausgabe von Flare:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="Get_Help">
<title>Get Help</title>
<body>
<p>
<indexterm>Get Help</indexterm>
<indexterm>Customer Service</indexterm>Get Help</p>
<p>
<ph conref="Resources/mcvars.dita#mcvars/variableId2" /> is committed to providing a variety of helpful resources to support your needs.</p>
<p>Online Help</p>
<p>From anywhere within <ph conref="Resources/mcvars.dita#mcvars/variableId1" />, click Help to browse our Online Help Center, where you'll find a list of Frequently Asked Questions (FAQs) for quick answers to common questions.</p>
</body>
</topic>
Und zum Vergleich dasselbe Thema wie im Texteditor von Flare:
<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">
<head>
</head>
<body>
<h1 class="NewPage"><MadCap:keyword term="Get Help;Customer Service" />Get Help</h1>
<p><MadCap:variable name="Text.Brand" /> is committed to providing a variety of helpful resources to support your needs.</p>
<h2>Online Help</h2>
<p>From anywhere within <MadCap:variable name="Text.AccountPage" />, click <strong>Help</strong> to browse our Online Help Center, where you'll find a list of Frequently Asked Questions (FAQs) for quick answers to common questions.</p>
</body>
</html>
Die Ausgabe verwendet die Dateitypen .ditamap und .dita, und auf der Hilfeseite von Madcap für Flare wird darauf hingewiesen, dass Sie die DITA-Struktur nicht nativ bearbeiten können:
Da DITA eine immer größere Rolle in der technischen Kommunikation einnimmt, werden immer mehr Tools verfügbar, um diese Art von strukturiertem Inhalt zu erstellen. In dieser Version können Sie Flare nicht verwenden, um DITA-Inhalte nativ zu bearbeiten. Sie können jedoch ein Drittanbieter-Tool (z. B. XMetal) verwenden, um Ihre strukturierten DITA-Dateien zu erstellen.
Nachdem ich jedoch ein wenig recherchiert hatte, fand ich dieses YouTube-Tutorial zum Erstellen benutzerdefinierter DITA-Elemente mithilfe des mc-dita-type- Attributs für Absatzklassen in Flare. Zum Beispiel:
p.Note
{
background-image: url('../Images/Icons/noteicon.png');
mc-auto-number-format: '{b}{color #9EB515}Note: {/color}{/b}';
mc-dita-type: quicktest;
}
Nach dem Erstellen der DITA-Ausgabe wird dieses mc-dita-type- Attribut zu einem Quicktest - Element-Tag in der Themendatei.
Bedingungen scheinen jedoch in der DITA-Ausgabe nicht zu funktionieren. Jeglicher Text im Thema wird eingeschlossen, unabhängig von den verwendeten Bedingungs-Tags.
Ich bin mir ziemlich sicher, dass die Antwort auf technischer Ebene nein ist. Aber das ist wirklich eine Frage, die auf einer anderen Ebene angegangen werden muss.
Das Besondere am strukturierten Schreiben ist, dass bestimmte Aspekte der endgültigen Veröffentlichung herausgerechnet werden, die dann bei der Veröffentlichung von Algorithmen wieder berücksichtigt werden müssen. Der Grund für das Ausklammern dieser Dinge ist, dass Sie verschiedene Algorithmen anwenden können, um unterschiedliche Arten von Ausgaben zu erzeugen.
Unterschiedliche strukturierte Schreibsysteme berücksichtigen unterschiedliche Elemente einer Publikation und unterstützen somit unterschiedliche Arten von Algorithmen zur Erstellung unterschiedlicher Arten von Inhalten.
Die Sache ist die, damit die Algorithmen zuverlässig funktionieren, müssen die Autoren die Strukturen richtig hinbekommen. Ein Editor mit einem festen Format wie Word, FrameMaker oder Flare backt die Strukturen dieser Sprachen und ihre Darstellung in die GUI ein. Die GUI basiert auf den Strukturen dieser Sprachen und passt nicht zu anderen Sprachen mit anderen Strukturen.
DocBook und DITA erfordern daher unterschiedliche Schnittstellen, die ihre Strukturen dem Schreiber offenlegen. Die Einführung einer anderen Sprache bedeutet die Einführung einer anderen Benutzeroberfläche.
Allerdings sind DITA und DocBook große, komplizierte Sprachen. Sie können Schnittstellen für sie erstellen, die nur einen kleinen Teil der Strukturen unterstützen, die die vollständigen Sprachen unterstützen. Diese sind möglicherweise einfacher zu verwenden, unterstützen jedoch nicht alle Funktionen der Sprache. Sie können sich diese Schnittstellen als mit DITA und DocBook verwandt vorstellen, so wie MarkDown mit HTML verwandt ist. Markdown ist viel einfacher zu schreiben als HTML, unterstützt aber nicht mehr als einen Bruchteil der HTML-Sprache.
Nahezu alle existierenden Schreibformate können in DocBook konvertiert werden. Das Ergebnis wird ein gültiges DocBook-Dokument sein, aber es wird nicht alle Funktionen von DocBook nutzen. Die Konvertierung anderer Formate in DITA ist aufgrund der Topic-Architektur schwieriger. Aber selbst wenn es funktioniert und eine gültige DITA-Datei erzeugt, werden nicht alle Funktionen von DITA genutzt. Flare-Inhalt könnte wahrscheinlich entweder in DocBook oder DITA konvertiert werden, aber der Inhalt würde nur die Strukturen enthalten, die von der Flare-Schnittstelle unterstützt werden. Sie würden nicht die volle Leistungsfähigkeit von Flare oder DITA erhalten.
Der Punkt ist, dass sowohl DITA als auch DocBook die Erstellung von Inhaltsstrukturen unterstützen, die mit einer Reihe von Algorithmen manipuliert werden können. Wenn Ihr Tool jedoch die Erstellung der Strukturen nicht unterstützt, die diese Algorithmen erfordern, können Sie sie nicht erfolgreich ausführen, selbst wenn sich Ihre Quelldatei technisch gesehen in DITA oder DocBook befindet.
Mit anderen Worten, Sie müssen von den Algorithmen ausgehen, die Sie auf Ihren Inhalten ausführen möchten. Die Algorithmen, die Sie ausführen möchten, erfordern bestimmte Inhaltsstrukturen, um zuverlässig ausgeführt zu werden. Sie müssen also eine Sprache wählen, die diese Strukturen unterstützt, und dann müssen Sie ein Werkzeug wählen, mit dem Autoren diese Strukturen klar und einfach erstellen können.
Wenn das Tool, das Sie jetzt verwenden, die Algorithmen, die Sie ausführen möchten, nicht unterstützt, wird es wahrscheinlich nicht die Erstellung der Strukturen unterstützen, die Sie zum Ausführen dieser Algorithmen benötigen. Sie benötigen ein Tool, das zu dem Format passt, das die Algorithmen unterstützt, die Sie ausführen möchten.
Monika Cellio