Die Redakteuse

Schlagwort: Schreiben

  • 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.

  • Kosten-Nutzen… und der Nutzer

    Sarah O’Keefe hat unlängst folgenden Satz getwittert:

    „Single sourcing can privilege organization needs over end user needs“

    Das hat mich an die Zeit erinnert, als ich im Studium die Standardisierung in der Dokumentation kennenlernte. Es wurde einem beigebracht, dass das total toll für den Nutzer ist, weil alles viel eindeutiger ist und damit verständlicher.

    Mein Gedanke lautete aber damals schon ungefähr:

    „Standardizing can privilege organization needs over end user needs“

    Was die Standardisierung von beispielsweise Syntax angeht, war ich schon immer etwas skeptisch. Meiner Meinung nach liegen die Vorteile hier mehr bei der „Organisation“, denn mit standardisierten Sätzen hat man eine höhere Wiederverwendung, niedrigere Übersetzungskosten. Hier ist der Kosten-Nutzen-Faktor für die Firma, bzw. den Redakteur echt prima.

    Aber ich finde es als Autor auch teilweise dröge standardisierte Sätze zu bauen. Als Nutzer die ganze Zeit nur „Klicken Sie hier. Klicken Sie da.“ zu lesen, ist noch un-spannender. Ziehtder Nutzer hier wirklich einen Nutzen draus? Ich glaube, dass diese Gleichförmigkeit viele Nutzer etwas abstumpfen lässt und sie dabei das eigentlich Wichtige auch eventuell überlesen. Kann man den Nutzer gleichzeitig bei der Stange halten und sich als Redakteur trotzdem das Leben einfacher machen? Ich weiß es ehrlich gesagt nicht. Das Thema „Leseanreize“ hatten wir ja schon mal, aber genügt das?

  • Links in DITA #3 – Relationship tables

    Mit den so genannten Relationship tables (reltable) kann man die Beziehungen zwischen Topics definieren. Hiermit implementiert man Verlinkungen, die nicht durch die Hierarchie (oder die anderen collection-types) festgelegt ist. (mehr …)

  • Links in DITA #2 – Hierarchien und collection-type

    Ich habe bereits vorgestellt, welche Möglichkeiten des manuellen Verlinkens es gibt. Wie gesagt, erschwert diese Methodik die Wiederverwendung eines Texts. Da Wiederverwendung jedoch einer der Kernpunkte von DITA ist, gibt es natürlich auch hier Mittel und Wege. Und zwar indem man die Verlinkungregeln in die Maps auslagert. So kann man auch nur das verlinken, was in der Map drin ist und läuft nicht Gefahr tote Links zu erzeigen.
    (mehr …)

  • Links in DITA #1

    Der Link ist essentieller Bestandteil der Online-Welt. Gerade bei der Topicorientierung, in der Information quasi auseinandergerissen ist, ist er die beste Navigationsmöglichkeit für den Leser und stellt einen Kontext her.

    DITA ermöglicht einem einerseits manuell Links zu setzen oder sie automatisiert setzen zu lassen, indem man vorher den Beziehungsstatus definiert.

    Heute gibt es erst einmal etwas zu den Links, die man als Redakteur selbst direkt einfügen kann.

    <xref> – Inline-Links
    Diese Links setze ich manuell mitten im Textfluss. Etwa so wie diesen hier. Dieses Vorgehen ist eigentlich allgemein bekannt.
    Im Code sieht es so aus:

    hier

    Verlinken kann man alles von anderen Topics bis hin zu Webseiten (nur bei Links von generierten PDFs auf Online-PDFs muss man bei Verwendung des FOP aufpassen).
    Generell ist das Verwenden von Inline-Links aber eigentlich nicht so toll:

    • sie unterbrechen des Lesefluss und die Aufmerksamkeit des Nutzers. Will man den Nutzer wirklich mitten im Task in einen völlig anderen Kontext schicken? Eigentlich nicht. Höchstens wenn es sich um eine Handlungsvoraussetzung handelt.
    • ein Topic ist durch einen Inline-Link in der Regel schlechter wiederverwendbar. Verwendet man es wieder, könnte der Link kaputt gehen, weil das Linkziel in diesem neuen Kontext nicht vorhanden ist.

    <related-links>
    In der manuellen Variante der „Related links“ fügt man den Tag <related-links> ein und setzt die Links in einzelne <link>-Tags oder in eine <linklist>. Das Gute an diesem Tag ist, dass er am Ende des Topics gesetzt wird, also den Nutzer nicht aus dem Kontext reißt. Aber auch in dieser Option steckt der Nachteil, dass die Wiederverwendung des Topics eingeschränkt wird.

  • IBM Task Modeler: die Anfänge einer Dokumentation

    Ich bin in den letzten Monaten mehr land unter als mir lieb ist und man sieht doch eindeutig an der Zahl meiner Blogeinträge, dass ich nach Feierabend kaum noch Energie für TR abseits meiner Arbeit aufbringe. Dabei habe ich doch gerade in dieser arbeitsreichen Zeit wieder einigen Stoff gesammelt 🙂

    Tasks konzipieren
    jeder Schreiber kennt das: da sitzt man also vor dem leeren Blatt / dem weißen Screen und muss irgendwie anfangen mit der Doku. Ich fange in der Regel so an, dass ich mich erst einmal selber als Dummy durch das Produkt klicke und mir Tasks notiere, die ich dokumentieren würde. Von Mike Hughes habe ich mir abgeschaut, die größte Prio auf die Tasks zu setzen, da sie für den Nutzer erst einmal das Wichtigste sind, denn dieser will in erster Linie etwas MACHEN.

    Ideal für diese Vorgehensweise ist der IBM Task Modeler, ein eclipse-basierte Editor mit dem man Topics und ihre Beziehungen / Hierarchien in einer Map visualisieren kann. Man hat die Wahl zwischen einer Baumansicht und einer Listenhierarchie-Ansicht. Hier mal ein sehr einfaches Beispiel in einer Baumansicht:

    Per Tastenkombination kann man sehr schnell Child-Topics ( Strg+Pfeil nach unten) oder Schwester-Topics einfügen und somit sehr zügig arbeiten. Man kann die Topics außerdem in der Anordnung per „Drag and Drop“ wild verändern, was meiner Arbeitsweise sehr entgegen kommt.

    Ich sammele immer zuerst alle Informationen bzw. Topics und schiebe /lösche / erweitere /verteile dann so lange bis ich die perfekte Struktur finde. Gleichzeitig kann ich im Modeler auch schon alle Metadaten für die Topics bearbeiten oder die Reltables.

    Tasks exportieren

    Wenn ich nämlich all das fertig habe, kann ich ganz einfach hergehen und diese schöne Struktur mit allen Informationen exportieren: File > Export from Model > Stub Topic Files

    Der Task Modeler generiert mir sogenannte Stub Files, d.h. Dateigerüste für jedes Topic. Diese Dateigerüste enthalten auch direkt alle Informationen, die ich eben eingegeben habe. Also für alle Tasks werden dann echte Task-Dateien mit den eingegebenen Titeln, Attributen etc. angelegt. Zusätzlich ich kann festlegen, dass in der exportierten Map auch automatisch die Referenzen auf die Stub Files gesetzt werden und die Dateinamen der Stub Files ihrem Topictyp entsprechen, d.h. dass beispielsweise alle Task-Dateien mit dem Präfix t_ im Ordner tasks abgespeichert werden. Und zack – hab ich die Grundlage zum weiteren Arbeiten.

    Vorsicht ist allerdings speziell im Deutschen geboten, wenn man Umlaute im Titel verwendet, denn dieser ist auch Grundlage für die Dateibenennung und ID-Vergabe. Und der Task-Modeler schreibt diese Umlaute auch gnadenlos in den Dateinamen und in die ID: das Topic Lösung finden bekommt dann eben auch den Dateinamen t_lösung_finden.dita. Früher oder später führt so etwas immer zu Problemen, je nachdem wo die Dateien weiterverarbeitet werden. Mein Workaround war irgendwann, dass ich Umlaute in den Titeln einfach ausgelassen habe und sie später nach dem Export im Editor einfügte. Das ist schneller als alle Dateinamen und noch die ID zu bearbeiten.

    Fazit – Task Modeler rockt!

    Der Task Modeler ist eine super Unterstützung in der Konzeptionsphase einer DITA-basierten Dokumentation. Das Konzipieren ist schön einfach und am Ende kommt auch per Knopfdruck direkt eine schöne Arbeitsgrundlage raus, nämlich die Map plus Dateien.

    Das Handling der Eclipse-Oberfläche ist allerdings für Nicht-Entwickler etwas gewöhnungsbedürftig – diese ganzen Panels sind einfach etwas verwirrend. Wärmstens zu empfehlen ist das Task Modeler Tutorial – diese Zeit sollte man sich nehmen, wenn man effektiv mit dem Tool arbeiten möchte.

    Noch nicht getestet – Import von bestehenden Maps

    Angeblich kann man andere Maps auch in den Modeler importieren, was sich natürlich für strukturelle Nacharbeiten sehr empfehlen würde. Allerdings habe ich das bisher noch nicht machen müssen 🙂

  • Schreib’s noch einmal, Sam!

    In Jacob Nielsens aktueller Kolumne kann man lesen, was für tolle Überschriften man doch auf BBC findet und wie super „web-usable“ diese doch sind.

    […] Web headlines, which must be:

    • short (because people don’t read muchonline);
    • rich in information scent, clearly summarizing the target article;
    • front-loaded with the most important keywords (because users often scan only the beginning of list items);
    • understandable out of context (because headlines often appear without articles, as in search engine results); and
    • predictable, so users know whether they’ll like the full article before they click (because people don’t return to sites that promise more than they deliver).

    Während ich diese Aufzählung lese, fühle ich mich sehr an mein Proseminar „Basiswissen Presse“ erinnert, indem genau das die Eckpfeiler der Aufgaben waren. Wir mussten regelmäßig Pressemitteilungen in einen Zeitungsartikel umzuwandeln, indem das Wichtigste in der Überschrift und im ersten Satz steht. Und nein, das war echt nicht so einfach und so manchen Artikel musste ich einige Male umschreiben, bis meine Dozentin es abnickte.

    Das ist klassisches Journalistenhandwerk und natürlich hat BBC das drauf. Wenn aber ein Web-Kenner wie Jacob Nielsen feststellen muss, dass genau das im Web das Herausragende ist, fühle ich mich einfach wieder bestätigt zu sagen: Nein, nicht JEDER kann schreiben.

    Die meisten Leute würden eher kaum auf die Idee kommen mal eben so einen Artikel für eine große Tageszeitung zu schreiben. Aber ein paar Sätze für die Webseite oder die Produktdokumentation sind dann natürlich „kein Problem“. Und die technische Redaktion darf dann ab und zu das Spiel „Rate, rate, wo kommt denn dieses Topic her?“ spielen 😉 Im Webbereich kann so eine Schreiberei dazu führen, dass der Leser nicht auf „Weiter“ klickt, folglich nichts kauft oder keine Werbeeinnahmen bringt und bei der Hilfe, dass der Leser nun doch den Support kontaktiert und damit weitere Kosten verursacht.

    Sooo einfach ist das alles also nicht. ein paar gute Gründe mehr dafür, warum nicht jeder technische Redaktion machen kann, hat Tom Johnson unlängst geliefert.

    Und Dilbert hat kurz davor das passende Bild abgeliefert (oh, ich wollte das noch ausdrucken und neben meinen Savage Chicken-cartoon hängen).
    Dilbert.com

  • Spaß, Spaß… wir wollen Spaß!

    Es ist wahr, was man so oft sagt: zwingt man sich erst einmal wieder zum Schreiben, fallen einem schon tausende Sachen ein, die man bloggen will 🙂

    Die Kollegen vom Joomla-Buch haben einen Blogpost zum Thema Humor in der technischen Doku gemacht. Den Ansatz finde ich recht interessant, wobei mir ganz persönlich hier noch gute Beispiele fehlen, um das ganze etwas zu veranschaulichen. Aber dazu muss man wohl den Vortrag der Kollegen auf der tekom-Frühjahrstagung besuchen, was mir nicht vergönnt sein wird, da mich der Rest des Programms nicht sehr anmacht. Aber hey, vielleicht sind sie so multimedial und filmen das ganze und laden es bei youtube hoch 😉

    Spaß beim Lesen – culture clash

    Ich habe schon relativ viel Fachliteratur auf Englisch gelesen und egal ob es ein englischer Artikel zu Goethe oder Heine war oder Steve Krugs Don’t make me think, ich hatte immer das Gefühl, das das beim Lesen mehr Spaß macht  als ein deutsches Buch. Da ist immer ein Augenzwinkern, eine kleine Anekdote oder ein lockerer Spruch dabei, die einem zum Schmunzeln bringt und dabei die Identifiktation und das Verstehen fördert. Allein eine Buchreihe mit dem Titel „A brain-friendly guide“ bringt mich schon zum Lachen 🙂

    Gerade im wissenschaftlichen Bereich scheint es in Deutschland wichtig zu sein im Schriftlichen immer bierernst zu bleiben, weil man sonst eben auch nicht ernst genommen wird. Ich glaube kaum, dass die Amerikaner humorvoller sind als die Deutschen, denn humorvolle Vorträge u.ä. habe ich schon oft erlebt, nur im schriftlichen Bereich ist vieles noch sehr verschnarcht.

    Spaß in der Doku?

    Leseanreize zu schaffen ist auch für uns Doku-Schreiberlinge wichtig – der Leser soll nicht beim Anblcik schon denken: „Ok, ne. Ne, das les ich nie. Oh, mein Gott!“. Aber mit dem Humor ist es so eine Sache, finde ich. Sehr oft konsultiert der Leser die Doku in einer Stresssituation:

    &%/*!$ nochmal! Warum macht das Ding nicht was ich will?! Wo ist die HILFE?

    Ich persönlich drehe ab, wenn mir jemand in Stresssituationen schriftlich oder persönlich mit Humor kommt (wem ist schon zum Lachen zumute, wenn Word kurz vor dem Fertigstellen der Doku die Formatvorlagen des 200-Seiten-Dokuments zerschießt?). Daher kann ich mir vorstellen, dass so mancher Leser sich veräppelt vorkommt, wenn man auf die lustige Tour kommt.

    Es ist ja auch eine Frage des Produkts, um das es geht: habe ich eine Business-Software, die von eher konservativen Leuten gelesen wird oder eine Messenger-Software bei der die jüngere Clientel den einen oder anderen lockeren Spruch cool findet? Passt der Humor zur restlichen Kundenkommunikation?

    Spaß in Beispielen

    Mein persönlich einziges Einsatzgebiet von Humor in der Doku sind Beispiele. Hier kann man den Nutzer mit einem kleinen Seitenhieb auf das Alltagsleben abholen, wie etwa hier:

    Angenommen Ihr Kollege ist in Urlaub gefahren und hat vergessen das Dokument vorher zum Bearbeiten freizugeben und Sie müssen es nun eigentlich veröffentlichen. In diesem Fall können Sie diese Funktion…

    Jedem Büromensch fällt doch dazu gleich eine eigene Anekdote ein, was so der ein oder andere vor dem Urlaub vergessen hat zu tun 😉

    Ganz abgesehen davon, dass es einem auch als Schreiberling Spaß macht, solche Beispiele zu erfinden. Hier kann man wirklich kreativ werden und mal vom Sachlichen wegkommen.

  • Was soll ich schreiben?

    Hey, als technischer Redakteur ist das doch eine einfache Frage: „Dokumentier halt, was man mit dem Produkt machen kann und was man nicht machen sollte.“  Soso…

    „Dazu braucht man doch keine Hilfe!“

    Ich habe gerade das erste Mal nach langer Zeit mal wieder ganz von Grund auf Hilfe zu einem neuen Produkt geschrieben. Und zwar für ein Produkt, das richtig schön zu bedienen ist. Bei dem man als Nutzer denkt: „Woohoo, wie konnten sie nur wissen, dass ich genau sowas will!?“

    Tatsächlich erschließen sich die Basisfunktionen der Applikationen fast wie von selbst. Kurzum: es hat Spaß gemacht, dieses Arbeitsfeld zu erfassen. Daher hab ich auch oft gehört, dass ich doch dieses oder jenes nicht zu dokumentieren bräuchte, weil es doch wirklich selbsterklärend sei.

    „Formatieren Sie Ihren Text fett.“

    Ich fing also an alle Tasks zu erfassen, die man als Nutzer so machen kann. Sollte ich nun wirklich dokumentieren soll, wie man in einem Texteditor seinen Text fett oder kursiv formatiert? Mein Gott, das weiß doch JEDER. Hier fand ich die Bestärkung es doch zu tun:

    […] we have to cover every topic—yes, even niche topics—in fact, especially the niche topics. Perhaps only five users might ever read a particular topic, but if that’s the topic they need and we get them there fast, their customer satisfaction level shoots through the roof. (Mike Hughes)

    […] Help needs to be a mile wide—it must cover everything—and 30 seconds deep—tackling only small amounts of detail at any given point.

    Wenn wir alles dokumentieren, heißt das auch, dass wir den Nutzer mit allem konfrontieren. Ich ganz persönlich finde es belustigend, aber auch ärgerlich, wenn mir jemand einen Text entgegenwirft mit einer Anleitung wie ich Text fett formatiere. Ich brauche das nicht, ich will das wirklich Wichtige wissen.  Das heißt, man muss nach dem Schreiben noch den richtigen Weg finden, die Information zu strukturieren und anzubieten, und sei es nur eine wirklich gut funktionierende Suche (und DAS ist echt nicht selbstverständlich).

    Nur noch 30 Sekunden

    Ich glaube es wirklich, dass nach 30 Sekunden, wenn nicht soga weniger, der Nutzer genug hat. Aber manchmal ist das schwer in Einklang zu bringen, dass man dem Nutzer auch sinnvolle Information mitgeben will. Angenommen ich habe eine Konfigurationsseite und möchte dem Nutzer genug Entscheidungshilfen an die Hand geben; das wird einfach etwas länger werden, wenn ich nicht nur Handlungen nacherzähle. Das Dilemma, dass man als Nutzer Hilfe möchte, aber eben schnell, wird sich wohl nie wirklich auflösen.

    Was soll wirklich drinstehen?

    Oft genug findet man Anleitungen, in denen einfach nur die Oberfläche nacherzählt wird. Aber mal ehrlich, ein bisschen mehr Grips haben unsere Leser in der Regel schon. Warum erzählen wir Ihnen nicht einfach das, was sie wirklich nicht wissen können?

    • Wie ich schon festgestellt habe, sollte man das absolut Offensichtliche weglassen, also den Nutzer eben nicht darauf hinweisen, dass er mit dem Speichern-Button doch tatsächlich seinen Text speichert!
    • Das nicht Offensichtliche erwähnen, wie etwa, dass man ein Objekt zusätzlich auch über Drag&Drop bewegen kann und nicht nur über die Schieberegler.
    • Man sollte nicht bloß nacherzählen WIE der Nutzer etwas machen kann, sondern WARUM er was machen könnt. Das heißt:
      • Entscheidungshilfen  geben:
        „Wenn Sie Ihr Blog auch für Suchmaschinen sichtbar machen, kann es prinzipiell vom jedem gefunden werden. Bei einem privaten Blog sollten Sie Suchmaschinen besser blockieren.“
      • sinnvolle Starthilfen / Beispiele geben:
        „Zeigen Sie am besten maximal 5 Artikel pro Seite an, damit die Seiten nicht zu lang werden und damit unübersichtlich werden.“

    Fazit

    Hey, wenn die Daseinsberechitgung eines Texts angezweifelt wird, werde ich ab sofort heroisch jedem Produktmanager, Conceptioner & Co. sagen: „Wenn ich auch nur einem Kunden damit weiterhelfen konnte, dann hat sich dieser Hilfetext gelohnt.“

    Mein wichtigstes Fazit ist für mich den Nutzer nicht nur mit „Tu dies – klick das“ zu konfrontieren, sondern auch mit „Tu dies – das ist für jenes nämlich gut!“ Und dabei trotzdem im Blick zu behalten, diese Infos nicht zu überbordend zu gestalten.

  • Standardisieren ohne Kopf

    Wenn man sehr viel schreibt, passiert es gut und gerne, dass man sich bestimmte Schreibmuster angewöhnt ohne darüber nachzudenken.

    Sehr beliebt sind bei mir Füllwörter jeder Art, die ich bei meiner Master-Thesis am Ende per Strg+F suchen konnte, weil es zur der Zeit immer die dieselben zwei waren 😉 Ansonsten sind Schreibmuster für einen technischen Redakteur nicht das Schlechteste, da man schließlich standardisiert arbeiten soll. Aber in manchen Fällen denkt man vor lauter Standardisierung nicht mehr richtig nach.

    Ich hab gestern bspw. ein kleines Review der Doku gemacht, an der ich gerade arbeite. Ich habe nach dem Muster „Klicken Sie auf XY, um das den Leuten ein X für ein U vorzumachen“ gearbeitet. Und zwar sehr streng. Zu streng. Zu kopflos.

    Sätze wie „Klicken Sie auf Speichern, um zu speichern.“  erzeugen nur Textmüll und bringen keinen Mehrwert im Gegensatz zu „Klicken Sie auf Speichern.“. Vermeide das Offensichtliche, sag ich da nur!