Die Redakteuse

Schlagwort: Variantenmanagement

  • Task-Grenzen

    Beim Texten von Tasks gibt es etwas, was mich als Redakteur von Software-Doku seit den Anfangstagen als TR regelmäßig verrückt macht: wo hört ein Task auf und wo beginnt der nächste? Speziell bei Handlungen, die im Großen und Ganzen dasselbe Ziel haben, aber die man auf verschiedenen Wegen erreichen kann.

    1 Handlung = mehrere Varianten

    Ein gängiges Beispiel ist das Einfügen von Bildern, z.B. in ein Blog oder eine Website.

    Ziel: Bild in den Artikel einfügen

    Möglichkeiten zur Zielerreichung:

    • Bild vom PC hochladen
    • Bild aus dem Web verlinken
    • Bild aus vorhandener Galerie einfügen

    Die Handlungen sind in den ersten Schritten typischerweise identisch, aber unterscheiden sich dann in den meisten folgenden Schritten. Nur das Ziel ist am Ende dasselbe: ein Bild wurde eingefügt. Ich bin nie so ganz schlüssig, was ich in solchen Fällen tun soll.

    Option 1:Rigoroses Splitten

    ich teile das ganz rigoros in drei Topics auf. Der Nutzer sieht ganz spezifisch an der Topic-Überschrift um was es geht.

    • Bild vom PC hochladen
    • Bild aus dem Web verlinken
    • Bild aus vorhandener Galerie einfügen

    Das Problem ist, dass ich auf diese Weise ganz schön viele Topics produziere, die den Nutzer fast erschlagen. Zudem gibt es auch Nutzer, die nur wissen, dass sie ein Bild einfügen wollen, aber mit den drei Optionen einfach so nichts anfangen können. Und prinzipiell sucht wahrscheinlich auch ein erfahrener Nutzer eher nach „Bild einfügen“ als nach „aus dem Web verlinken“.

    Option 2: In ein Topic verpacken

    Es gibt einen Ort an dem der Nutzer nachschaut – bingo, da sieht er alles was zu dem Thema wissen muss.

    • Bild einfügen

    Das Problem ist, dass man so unter Umständen ganz schön lange Topics produziert – zudem kann man es kaum in die SITA-Struktur packen. Es gibt zwar Handlungsvarianten (choice), aber die beziehen sich meist auf einen Handlungsschritt, und nicht einen ganzen Handlungsstrang. Sowas wäre mir am liebsten:


    Um ein Bild hochzuladen, wählen Sie eine der folgenden Möglichkeiten:



    Um eine eigene Datei hochzuladen...
    ...


    Um eine Datei aus dem Web zu verlinken...
    ...


    Aber das lässt DITA nicht zu. Mir ist auch klar warum: damit fällt es einem leichter mehrere Topics in eins zu verpacken. Und man will ja immer nur ein Thema pro Topic. Dummerweise ist das Leben nicht immer so einfach. Hier würde ich mir zumindest mehr Flexibilität wünschen.

    Fazit
    Hält man sich streng an die DITA-Informationsarchitektur kann man eigentlich nicht anders als das auf 3 Topics zu splitten. Aber aus Nutzersicht gefällt es mir nicht.

  • Bedingter Text in der Praxis

    Oder nennen wir ihn auch „conditional text“. Gemeint ist das Prinzip Texte mit einem Attributwert zu versehen und beim Generieren festzulegen, ob Elemente mit diesem Attribut inkludiert oder exkludiert werden.

    Eigentlich eine feine Sache, um Produktvarianten zu handhaben (So geht es in XMetal).

    Praxisbeispiel

    Nun wende ich das ganze wirklich zum ersten Mal an und zwar hier:

    Das Feature ist eigentlich dasselbe, nur dass es in Produkt A als „Copyright-Zeile“ auftaucht und automatisch ein ©-Zeichen eingefügt wird. Während in Produkt A1 das Feature „Fußzeile“ heißt und nichts automatisch eingefügt wird.

    Dem Featurenamen hab ich daher in ph-Tags gepackt und sie entsprechend mit product_a oder product_a1 attributiert. Sieht eigentlich gut aus und am Ende kommt auch das raus, was ich will!

    Haken an der Sache?

    In obigemFall war das ganze einfach, weil die Features denselben Genus aufweisen und beide im Singular sind. Angenommen „die Fußzeile“ hieße eigentlich „der Fußmarker“ – da müsste ich beispielsweise Artikel oder Pronomina in den ph-Tag mitaufnehmen. Das obige Beispiel sähe dann so aus:

    Irgendwie hab ich das noch unbegründete Gefühl, dass genau solche Fälle beim Übersetzen Ärger machen können, aber noch hab ich keine Beispiele dazu gefunden…

  • DITA-Output filtern mit XMetal

    Wiederverwendung und Varianten
    Das Filtern wird in Zeiten der Wiederverwendung früher oder später notwendig. Man hat beispielsweise ein Produkt, dass es in einer Light-Version und einer Vollversion gibt. Natürlich werden sich hier die Hilfetexte zum größten Teil überschneiden – bis auf die kleinen Ausnahmen, wo dann in der Vollversion hier noch ein Schritt weniger ist und dort eine Option mehr verfügbar. Man hat also eine Wiederverwendungsquote von 90%, aber was tun? Die Hilfetopics nun zweifach vorhalten? Ne, da sträuben sich jedem guten Redakteur die Haare. Redundanz, nein danke!

    Nun, wie wär’s, wenn man einfach alle Varianten in eine Datei schreibt und die Teile, die nur für ein Produkt gelten mit einem Attribut versieht? Und dann beim Generieren einen Filter definiert, der nur Teile generiert, die einen bestimmten Attributwert enthalten? Klingt cool – isses auch!

    Attribute in DITA
    Es gibt für DITA schon einige fest definierte Attribute, die man an fast jeden Tag vergeben kann. Es sind gängigen Attribute nach denen man in der Doku filtert und für die man frei Werte definieren kann:

    • product
    • audience
    • platform
    • outputclass (erst ab DITA OT 1.4 unterstützt)

    Zu guter Letzt gibt es das otherprops-Attribut, das so ziemlich alles enthalten kann. Eine Art Auffanglager für den Rest sozusagen.

    DITA-Attributvergabe im XMetal

    Wir nehmen uns nun ein Beispiel, in dem ein bestimmter Handlungsschritt nur in der Print-Hilfe auftaucht und in der Online-Hilfe nicht, weil die Online-Hilfe kontextbasiert ist und ein Zwischenschritt wegfällt, der aber in der Print-Version nötig ist.

    Eigentlich sollte man dazu ab DITA 1.4 das Attribut outputclass verwenden, da ich aber noch auf DITA 1.3 arbeite, werde ich also das otherprops-Attribut verwenden. Ich markiere den <step> und  schreibe im Attribute Inspector einfach den Wert hinein nach dem ich filtern möchte.

    Der Nachteil hierbei ist, dass je nach Attributwert einem anderen Redakteur nicht unbedingt von Namen her sofort klar ist, nach was hier gefiltert wird. Wenn ich z.B. handbook als Wert eingebe, kann das einerseits bedeuten, dass ich für den PDF-Output etwas filtern möchte (es also eine technische Bedeutung hat) oder aber für den Dokumenttyp „Handbuch“ (was dann eher inhaltliche Bedeutung hat).

    Filterregeln in XMetal anlegen

    Hierzu muss man folgende Datei öffnen: c:\Programme\XMetaL 5\Author\Conditional Text\configs\ct_config.xml

    Hier kann man nun seine Attributwerte definieren und festlegen, wie diese in der Filterauswahl angezeigt werden. Ich habe hier den Attributkomplex zu otherprops bearbeitet. Für jeden Attributwert definiert man einen <value>-Tag, in name steht der Attributwert und in title steht der Anzeigename in der Filterauswahl.

    ´[....]

    Filterregeln auswählen

    1. Auf File > Generate Output from DITA map klicken.
    2. Im Dialog auf Show/Hide Conditional Text klicken.
    3. Hier kann man nun auswählen, welche Filterkriterien für den aktuellen Output gelten sollen.
      Ich will nun beispielsweise eine Online-Hilfe generieren, d.h. der <step>, der nur für Handbücher gilt, soll nicht generiert werden. Also klicke ich das Filterkriterium Onlinehelp an. Es wird alles generiert, was keinen Wert für dieses Attribut hat oder eben genau diesen Wert, d.h. der <step> mit dem Attributwert Handbook wird hier nicht generiert werden.

    Ergebnis
    Am Anfang steht also dieser Code:

    Öffnen Sie das Programm.

    Klicken Sie auf

    DateiNeu

    Editieren Sie die Datei.

    Und am Ende dieser Text:

    1. Klicken Sie auf Datei > Neu.
    2. Editieren Sie die Datei.