Content Strategies and the spirit of DITA

The mini-tracks during Content Strategies 2016/ DITA North America have shown DITA development in so many fields of content and communication:Washington Monument

  • Lightweight DITA
  • Taxonomy
  • Video
  • Translation
  • Learning and Training
  • Medical Industry
  • DITA for the Machine Industry

The spirit of DITA, as Michael Priestley reminded us in one of his presentations, is to ADAPT. The more options and tools are emerging, the more ways there are to connect and grow towards Enterprise Content Management, to consolidate, coordinate, collaborate on common content across departments.

From one track to the other, conference attendees could learn about minimal content models that “can still go crazy” (Michael Priestley), ditamaps handling decision points as a dynamic flow (Chris Nitchie), cross-format content in ditamaps (Carlos Evia), shaping the content with taxonomy (Joe Pairman), card-based content authoring and delivery (SAP), simple DITA format for translation (George Bina), augmented linguistic review (WhP).

To encourage even more teams to adopt DITA, I presented the model2dita project and was glad to see it struck a chord, just as it did last November at DITA Europe in Munich.

model2dita: Generate your DITA project structure from the information model

What is your process when you start a new documentation project in DITA? How do you decide on the content and by which magic does it turn into DITA topics and maps? To develop effective, user-oriented information, you should invest most of your time in researching your audience and in task analysis rather than clicking New > File > Map, New > File > Topic and dragging topicrefs

New DITA writers often find it difficult to envision the transformation of the information outline to the actual DITA structure. Others don’t even have the habit of starting with an information model in the research phase of a project.

The prezi shows the importance of the modeling phase in the writing workflow, as well as some methods and tools for translating the model into a DITA project structure automatically.

Moreover, I owe a hat tip to Paul Zimmerman (CISCO) for mentioning my last year’s project, rst2dita, about markdown round-tripping in his presentation “Get to Gittin’ On: Integrating code and content management in Git“.

Touring Reston, VA and Washington, DC was remarkable. See you all again in Munich in November.

Auf ein glückliches DITA Jahr!

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!

Upcoming workshop: Building a DITA pilot project

One more month to go until TCUK 2015 in Glasgow. Have you booked your package yet?

While preparing for the three-hour workshop on Building a DITA pilot project, the sound of bagpipes is bringing Scotland closer, here in Germany. Can’t wait to meet TCUK delegates again and to host another DITA workshop.

You are considering migrating to DITA and would like to see a proof of concept, but don’t know where to start? Bring your laptop to the DITA Pilot workshop and you’ll see how quickly you can get started. We’ll just follow a few steps:
1. Design phase:
– Identify use cases and task analysis
– Outline the information model and its modules
– Set up the project structure

2. Production phase:
– Writing the topics and the map
– Publishing PDF and HTML
– Reviewing

It does not take long to be productive in DITA and to prove its value to your team. Take a running project back to the office with you and turn the DITA business case into reality with a demo for your colleagues.

September 29, 2015, 2:00 pm to 5:00 pm
The Beardmore Hotel and Conference Centre, Hall: Clyde
TCUK Website: http://technicalcommunicationuk.com/

DITA Pilots, on your marks…

DITA linking best practice at IEn2015

Infomedian of the YearThe three days at Information Energy 2015 in Utrecht have passed too quickly. Everyone seemed to feel at home, the sessions were interactive and fun, speakers and attendants eager to share information and show how they create and publish content in most diverse forms and channels… that’s what makes an infomedian. To round up the experience, apart from teaching a master class and giving a presentation, I had the honor of giving a short interview and being part of the jury in one of the workshops.

Seats2Meet
The venue also gave it special “energy” – first, Master Classes and presentations at Uni Utrecht, a historical site with classical and retro chambers where the eyes of scientists, professors and artists watched us from old paintings or billboards, followed by workshops at Seats2Meet, a very interesting concept with themed lounges in vintage look.

After the full-day Master Class on the pre-conference day, I also gave a short presentation the next day about DITA Linking Best Practice. We have seen examples and done exercises in the workshop. We have also talked about structured, topic-oriented writing and about DITA architecture: map structure, reuse strategy, authoring environment and publishing pipelines. The presentation afterwards was just the shorthand version of the workshop, but it served to start further discussions. Thank you all for attending! It was great meeting everyone in Utrecht.

Enjoy the prezi and let me know your thoughts:

DITA Linking - prezi

Click the image to open the Prezi slideshow

For the advanced use of keys on topic references, don’t miss the contributions of Gnostyx and Eliot Kimber to the dita-community repository: dita-demo-content-collection

So how are you managing your content linking?

Related posts 😉

Mit Legos in Stuttgart

Auf dem Weg nach XML-Prag, habe ich versucht meine Artikel-Reihe über die letzten Konferenzen weiter zu schreiben. Ich schreibe diesen Artikel auf Deutsch, weil es gerade um die tekom Jahrestagung 2014 in Stuttgart geht. Ich hatte die Tagung in den vorigen Jahren schon besucht, diesmal aber habe ich meinen ersten Vortrag und einen Workshop auf Deutsch und nacheinander sogar gehalten.

Mein Workshop – Das DITA-Implementierungsprojekt – und der Vortrag – Verstehen Sie DITA-Architektur? – haben erst am dritten Tag stattgefunden. Nichtdestotrotz waren sie gut besucht. Ich hätte mir gewünscht, dass die Workshopräume besser isoliert würden und jeder Teilnehmer einen Platz am Tisch hätte, sodass man bei den Übungen mitmachen konnte… So mussten wir Vieles überspringen, aber die Gruppe war trotzdem aktiv und stellte gute Fragen.

DITA Implementierung - Folien

Gleich danach dürfte ich mehr über DITA-Architektur im riesigen Plenum-Raum berichten… was so komisch auf mich wirkte, dass ich fühlte wie mein roter Faden dahinschwindet. Die Blokade war glücklicherweise nicht von Dauer, da gleich in der nechsten Woche habe ich noch einen Vortrag gehalten und es lief alles prima. Für den Teil über DITA-Architektur hatte ich eigentlich ebenso einen Workshop vorgeschlagen, dürfte aber diesmal nur einen Vortrag daraus machen. Vielleicht klappt es mit dem Workshop bei der Jahrestagung 2015 🙂 So würde ich meinem Publikum durch konkreten Beispielen und Übungen beibringen, was ich ihnen noch schulde.

DITA Architektur Folien

Darüberhinaus war ich in Stuttgart zum ersten Mal als Aussteller mit meinem neuen Arbeitgeber PANTOPIX dabei. Wir haben Freunde und Messebesucher eingeladen, mit uns über ihren Datenmodellen zu reden und dabei mit den Lego-Steinen zu spielen. Außer einer Reihe von Firmenlogos, entstanden ein paar einzigartige Objekte aus der Zusammenarbeit der Standbesucher. Danke fürs Mitmachen!

PANTOPIX Legosteine

Spice up Your DITA Workflows – Flashback tekomRS

Part two of the flashback series recalls my prezi “about… DITA, of course” as @georgebina said, at the tekom Europe Roadshow in Bucharest.

The RoadShow story

After George has shown their efficient recipes for using DITA along the software documentation lifecycle at Syncro, I just suggested a few more spices to make a writer’s life a bit easier.

Sometimes it feels like the only constant in a technical writer’s work is change. Whether in agile or waterfall, project teams tend to place documentation towards the end of the process, or leave them at least one iteration behind. So after documentation is reviewed, approved, integrated in the kit and sent to translation, you notice the final seasoning: “minor” changes in the product right before the release. A modified label here, a moved button there… are exceptions to the “code freeze”.

Spice up your DITA workflows
But change is good, and you’re already at great advantage if using DITA. Indeed, you can make your documentation flexible and agile, by adding a few scripts to your DITA projects, to keep up with the changes in the products you are documenting.

Let’s see some examples for frequent updating of:
– strings in the user interface
– reference code
– application screenshots
– in-line code documentation


In the case of GUI strings, you can use keys in DITA, so that you wouldn’t have to worry about changes in all the topics. You just update the values in a keymap, or even use different keymaps in the same project, for different versions of the product.

<step>
   <cmd>Under <option keyref="mnu_sound-sch"/> select
     <uicontrol keyref="btn_nosound"/>.</cmd>
</step>

The special spice would be generating the keymaps on the fly, with a script like “ini2dita”, “csv2dita”, “xls2dita”… Talk to your developers and see how you can integrate the docs with the localization strings.


Keeping sources like the code samples, or 3rd-party licenses, in separate files, allows you to integrate them in your DITA content with coderef, increasing the flexibility of your projects.

<stepxmp>
   <codeblock outputclass="language-ini">
      <coderef href="codesample.bat"/>   
   </codeblock>
</stepxmp>

If you are using screenshots in your documentation, it is also best practice to refer to them by keys. Thus you can have separate sets of images for various product flavours and languages.

<stepresult>
   <image keyref="scn_sound-settings"/>
</stepresult>

Imagine you could even have the screenshots generated automatically. Wouldn’t that save a great deal of time? Tools like AutoHotkey and WinSpy might help.


Another advantage with DITA is you can apply an XSLT transformation of the in-line code documentation written by developers, like for example Python docstrings in rST, and even do the round-trip between rST and DITA formats. This method allows developers to keep writing in their favourite environment and you can even supply edited versions back to them in the same form. More about this in April at DITA NA in Chicago.

With these few seasoning ideas for your DITA workflows, you can save a lot of time and frustration when updating documentation projects, and you increase their accuracy and consistency. Give it a try!

Implementing DITA – Workshop Flashback TCUK14

Finally catching up with my posts, starting a series of scrapbook-like articles about the events I attended in the past few months. I should be quick, as more events are coming soon…

Brighton Royal Pavilion

September 2014 in Brighton was the first time I attended TCUK. Met some old friends, made some new ones, ate good sushi, attended interesting sessions and I had a great group to work with in the DITA workshop.

The workshop theme was “Implementing DITA – The work beyond the business case”, aiming to briefly present each implementation phase, to understand what the project team would have to go through and what the project plan would look like.

Have you been told that implementing DITA or migrating to a structured authoring environment would take at least two years and a six-digit amount from your budget? That might be true, but you should understand what lies beyond the business case, in order to sustain your team effectively.

Let’s walk through the phases of the DITA implementation project together and see what the project plan contains, what new skills your team requires, which tasks you can prepare in-house, and how DITA tools and architecture can work best for you.

We’ll discuss and practice:

  • the implementation project plan
  • content inventory and analysis
  • information modelling
  • reuse strategy
  • DITA architecture
  • DITA templates
  • changes in the documentation workflow with new team roles

After attending this workshop, you will be ready to present the components of a DITA implementation package to your team. Only after getting their commitment and motivation, you can kick off a successful implementation.

Looking forward to TCUK15, here is my “storified” workshop report. Many thanks to the restless and enthusiastic John Kearney (@JK1440) who live-twitted the event.

Storify: Implementing DITA (Workshop TCUK14)

Click the photo to view the story of “Implementing DITA – The work beyond the business case” on Storify