Category Archives: Technical Writing

DITA Roadmap 2017

by

DITA-Anwender Bodensee lädt ein

icon DITA-ABNach einem erfolgreichen ersten Jahr, präsentieren wir stolz und unter neuem Logo unseren Meetup-Kalender für 2017.

DITA-Musterprojekte schreiben, 22.02.2017

Unsere erste Aufgabe in 2017 lautet “DITA-Musterprojekte schreiben”.

Ziel: Dokumentation in DITA-XML-Struktur in verschiedenen Komplexitätsstufen schreiben und auf GitHub hochstellen.

Zeitraum: Feb. – Juli 2017

Warum wir das tun? Unsere Arbeit wird sowohl Redakteuren als Beispiel, als auch Beratern und Tools-Herstellern als Vergleich- oder Qualitätssicherung-Material kostenfrei zur Verfügung stellen.

Wir werden selber dabei mehr über DITA lernen und wir werden weitere Meetups darauf bauen.

Machen Sie mit!

DITA-OT Ausgaben selber anpassen, 22.03.2017

Bringen Sie Ihre DITA-Projekte und Layout-Anforderungen mit und lernen Sie in unseren Single-Source Publishing Tutorialien, wie man die Publikationen selber anpasst:

  • “Mein erstes DITA-OT Plug-in” Franz-Josef Knelangen zeigt wie man die PDF-Ausgaben des DITA-OT selbst anpasst und dass das alle Technikinteressierten mit XML- und DITA-Grundkenntnissen hinbekommen können.
  • “Ein Inhalt – verschiedenste Layouts” Markus Wiedenmeier demonstriert die Automatisierung verschiedener Layouts, z.B. durch die Automatischen Vorgabeseitenzuweisung in FrameMaker.

DITA-Projekte lokalisieren, 19.04.2017

Unsere zweite Aufgabe in 2017 lautet “DITA-Projekte übersetzungsgerecht schreiben”.

Ziel: Best Practice über Terminologie, Lokalisierung und XLIFF-Generierung der Dokumentation in DITA-XML-Struktur.

Zeitraum: April – Aug. 2017

Warum wir das tun? Im Rahmen dieses Projektes tauschen wir unsere Erfahrungen mit Terminologie, Übersetzung und XLIFF aus, wir recherchieren und sammeln bewehrte Praktiken, um diese mit der DITA-Community zu teilen.

Wir werden selber dabei mehr über DITA und Übersetzungsgerechtes Schreiben lernen und wir werden weitere Meetups darauf bauen.

Machen Sie mit!

DITA-Markdown Roundtrip, 24.05.2017

Unser Jubiläum feiern wir  mit dem Kick-Off eines Geek-Projektes: “DITA-Markdown Roundtrip”.

Ziel: Markdown-Texte mit DITA-Projekte bidirektional integrieren und mit GitHub versionieren

Zeitraum: Mai – November 2017

Warum wir das Tun? Kleine Teams arbeiten oft mit Markdown-Sourcen und GitHub-Versionierung. Wir möchten in Erfahrung bringen, wie man DITA Doku-Projekte mit weiteren Texten in den verschiedene Markup-Sprachen integrieren, versionieren und pflegen kann.

Ist Ihnen das Thema bekannt? Machen Sie mit!

“The Key must be free”, 21.06.2017

Indirekte Verlinkungen (Keys) sind bei Weitem das spannendste Thema in DITA-Projekten. Wir testen zusammen die verschiedenen Verlinkungsmethoden und vergleichen ihre Vorteile und Nachteile.
Bringt eure schwierigsten Projekte mit!

DITA-Tools Battle, 19.07.2017

Wir haben seit Februar an die DITA-Musterprojekte gearbeitet. Nun wird die Zeit, die verschiedenen DITA-Tools zur Probe zu stellen und zu zeigen, was es heisst, mit einem offenen Standard zu arbeiten: Unsere Musterprojekte soll man in allen Tools öffnen und publizieren können.

Tools für DITA-Lokalisierung und Terminologie, 23.08.2017

Seit April recherchieren wir bewehrte Praktiken zu “DITA-Projekte übersetzungsgerecht schreiben”. In unserem August-Workshop vergleichen wir die Umsetzung manchen Übersetzung- und Terminologie-Tools anhand von unseren DITA-Musterprojekte.

Sneak-Peek der Herbst-Konferenzen, 20.09.2017

Im Herbst nehmen wir immer an TD-Konferenzen teil, sei es als Teilnehmer, Aussteller oder Referenten. Deswegen benutzen wir unser September-Termin als Sneak-Peek (Kostprobe) unserer Beiträge und als Vorbereitung unserer Botschaft an der DITA-Community.

Top 10 DITA-Flops, 22.11.2017

Am “Buß- und Bettag” möchten wir darüber nachdenken, wie wir DITA gelernt haben, wie wir durch systematisches Ausprobieren und aus unseren eigenen (kleinen und großen) Fehlern gelernt haben.
Topic-orientiertes, semantisches Schreiben in der technischen Redaktion zu implementieren bedeutet Änderung, und Änderung ist… naja, ein schönes Chaos.

Die Meetup-Seite: DITA-Anwender Bodensee

Designing for Knowledge

by

Let me start with the takeaway from Information Energy 2016:

“Information cannot be intelligent. Intelligent means to propagate and enrich itself. It’s the processing that has to be intelligent.”

Andy McDonald, initiator of Documentation 4.0 and Infomedian of the Year 2016.

The Infomedian Arena is not new at Information Energy, but I must say that this year Wim and his team have done a great job at animating the arena and a few new forum sessions about the future of information and Documentation 4.0.

Infomedian Arena
Future of Information
Documentation 4.0

We have discussed statements about short term and long term expectations during the Future of Information forum, with Ric van Westhreenen, Eva Vangenechten, Joyce Karemann, Kate Thomas, Paolo Peraro, myself and other conference attendees. Common themes were augmented reality, artificial intelligence, open source collaboration.

During the two days I have seen quite an interesting mix of workshops and talks, from concepts and tools to real applications of content design. Just as a sidenote: the iRobot vacuum cleaner was mentioned in at least three talks, including mine. I wonder, what intelligent product is going to be the IEn favorite next year?

Marie-Louise Flacke on Troubleshooting
Troubleshooting, who cares?
Qian Li
Cultural Differences and User Instructions
Joe Gelb
IoT and support
Ray Gallon
Emotion and Techcomm
Stefan Gentz, Adobe
Structured authoring and multichannel publishing
Virtual and augmented reality for education
Future of documentation: virtual and augmented reality for education and technical support.

It is always interesting to see teams coming from different areas of information design working together and learning from each other. This was again the case in my wokshop and I was glad to see the discussions continued afterwards.

thinkDITA Workshop
Content modelling, customer journey mapping
thinkDITA demo
Showing DITA to web-designers

The closing Documentation 4.0 Forum assigned us some homework: join the doc4 LinkedIn group and help define the direction, terminology, consensus, and the skillset for techcomm.

Workshop Abstract: Modelling intelligent content

Know the touchpoints of your customers’ journey with your technical content. Use methods from your information architecture toolkit to research and plan for intelligent content.

Modelling Content Workshop IEn2016

In the age of connected experience, you have to accompany youraudience at all times and across media, as they research and use your product or service. Your role is constantly evolving from technical writer to communicator/ infomedian and you have to add skills and methods to your toolkit to create rich, intelligent content for your users.

Most technical communicators are already familiar with methodslike persona, use-cases and task analysis. In addition, let’s see how drawing the customers’ journey map and identifying their touchpoints with your content channels can help you discover an information model.

To deliver the right content that serves your audience where and when they need it, we’ll plan the main content publishing pipelines and we’ll wireframe a few publication types.

Finally, using a DITA-XML project, we’ll draft the information architecture (metadata, linking and reuse strategy) and we’ll set up the semantic markup structure of the content topics.

Join the workshop, June 8 on “Modelling intelligent content” to experiment with a few research and analysis methods and to create a sample content project.

DITA-Anwender Bodensee

by

Am 25. Mai fand der erste Meetup-Termin mit @axxepta und @thinkDITA in Langenargen am Bodensee statt.

Thema: XML & DITA in der Technischen Kommunikation.

Auf der Agenda: Kennenlernen, Erfahrungsaustausch und Programmideen für die regelmäßigen “DITA-Anwender Bodensee” Meetups.

DITA-Anwender Bodensee erste Meetup-Gruppenkarte

Unser Ziel: informelles Feierabend-Gespräch über DITA-XML-Themen, die uns Alle Interessieren. Weniger Folien, mehr zeigen und mitmachen. Ob man eine Frage stellen möchte, vor einem konkreten Problem steht oder hat etwas probiert und möchte mit uns teilen, nehmen wir gerne auf der Agenda. Es darf auch zu Bierabendgespräch nach 21 Uhr kommen.

DITA und XML sind kostenfreie, weltweite Standarde, die durchs Mitmachen und Mitteilen ihrer Anwender wachsen, sich ständig verbessern, sowie neue Methodologien und Tools herausfordern. Diese Kultur unterstützen wir auch durch die Meetup-Gruppe DITA-Anwendee Bodensee.

Also, Machen Sie mit? Wir freuen uns auf Sie.

Unfolding the Techcomm Box

by

[Originally posted on the Information Energy Blog, on March 29th.]

No doubt, the “techcomm box” keeps growing as we discover new dimensions of our digitally intertwingled lives. Without aiming to outline the history of technical writing here, I’d say we went through stages like typing, layouting, help authoring, single sourcing…

Folding-box template from templatemaker.nl

…and now, as we are still struggling to implement structured, semantic writing, we are unfolding one by one the sides of the techcomm box, extending our expertise towards multiple disciplines.

  • We are consolidating our roles as content experts through user research, information typing, minimalism, and instructional design.
  • We adopt standards that make our content interchangeable and part of the linked web of data for man and machine.
  • We collaborate across departments in our organizations, integrate with other systems and publish enterprise content.
  • We learn techniques from information architecture, UX, web design, and social media, to reach our audiences and accompany them along an intelligent, omnichannel experience.

Utrecht is the perfect place to meet and talk about information modeling and design. The infomedian gathering every June gets, as its name says, the information energy flowing and encourages us to think outside the box.

Looking forward to meet you in Utrecht and to discover further dimensions we need to explore as we “Design for Knowledge”!

Join the workshop, June 8 on “Modelling intelligent content” to experiment with a few research and analysis methods and to create a sample content project.

Auf ein glückliches DITA Jahr!

by

English version >> Happy DITA in Germany!

Die letzten Monaten in 2015 waren schon intensiv und ich habe wieder Vieles mitzuteilen, das ich unbedingt in Januar machen werde. Jetzt aber das Wichtigste wäre, mit folgender Aussage ins 2016 zu rutschen: DITA ist und bleibt hier. Das habe ich eine Weile her schon gesagt und sage es erneut, nachdem das steigende Interesse an DITA in Deutschland, unter anderem im November durch Workshops, Vorträge und Podiums im Rahmen der tekom Jahrestagung in Stuttgart und bei DITA Europe in München, noch deutiger wurde. Die DITA Gemeinschaft formt sich langsam, Werkzeuge und Systeme fangen an, DITA zu unterstützen und die Diskussion wird, naja, wenigstens leidenschaftlich.

Letzten September war ich ein bisschen enttäuscht und besorgt… etwa fünf Minuten lang 😉 als eine Gruppe deutschen CMS-Herstellern ein “Whitepaper” gegen DITA herausgegeben hatte. Sie hatten auch ein paar schlecht begründeten Folien, die ihren Kunden von DITA Implementierungen abraten sollten, mit auf einer Rundreise durch Europa genommen hatten. Die Amerikaner nennen solche Stellungnahmen FUD – Furcht, Unsicherheit, Zweifel (fear, uncertainty, doubt). Ich habe mich trotzdem überwunden, über das tragikomische Erwachen der dunklen Seite hinaus zu sehen und das Material durchzulesen. Meine Entscheidung war aber, an solchen nicht produktiven Versuchen nur wenig Aufmerksamkeit zu schenken. Ich werde mich weiter darauf konzentrieren, den DITA Einsatz in Europa und besonders in der deutschsprachigen Gemeinschaft zu unterstützen und Jeder ist willkommen, aktiv mitzumachen.

Auf Wiederstand zu stoßen ist vollkommen normal, wenn es um Änderung geht und kein Experte würde jemals sagen, DITA sei die beste Antwort auf allen Doku-Projekttypen. Doch wenn DITA den Anforderungen und den Audit-Ergebnissen entspricht, müssen professionelle Berater und System-Hersteller die Entscheidungen ihrer Kunden respektieren und ihre Flexibilität zeigen, anstatt eine hochmütige, selbstzerstörerische Antwort zu geben, wie – “Wir machen das seit zwanzig Jahren so und wir sehen keine Notwendigkeit unsere Architektur umzustellen.”

Während der tekom Jahrestagung in Stuttgart und kurz danach haben DITA Experten und Fans, mich eingeschlossen, über vielen interessanten, sowie über ein paar irreführenden Vorträge auf Twitter und Blogs berichtet. Mit viel Geduld und, anders als manche “anti-DITA Gastgeber”, ganz höflich haben Sie die Unklarheiten kommentiert.

Ebenso könnte ich hier noch einen Bericht mitteilen und Verlinkungen zu den Diskussionen auflisten, mein Gefühl über diese Sache sagt mir aber: ist schon genug! Wir sollten diese Debatten beiseitelegen, da der Wettbewerb zwischen Standards oder CMSes soll gesund und ausgeglichen laufen. Wir sollten uns auf die Vorteile für die Kunden und Redakteuren konzentrieren, anstatt uns an negative Aufmerksamkeitstricks zu versuchen. Als Berater und System-Hersteller sollten wir proaktiv zeigen, was wir für unseren Kunden und Partner besonders gut leisten können, egal ob mit DITA, PI-Mod, oder mit weiteren Strukturen (ich, zum Beispiel, habe mehrere davon studiert und implementiert).

Meine Botschaft an die technischen Autoren und Dokumentationsmanager lautet: Ihr Team muss entscheiden, niemals ein System-Hersteller, in Deutschland, wie anderswo auf der Welt, welche Standarde eingesetzt werden. Verfolgen Sie die Neuigkeiten und Anforderungen im Bereich technische Dokumentation und treffen Sie fundierte Entscheidungen. Involvieren Sie Ihre Teams, lassen Sie sie ihre Werkzeuge testen und genau die auswählen, mit denen das Team ihre geschäftliche Ziele erreichen wird.

Vielen Dank für ein wundervolles 2015 und wünsche Allen ein sehr Erfolgreiches 2016. Machen Sie Ihre Teams, Kunden und Anwender wunschlos glücklich!