Tag Archives: tekom

Mit Intelligenten Informationen begeistern

by

So lautete das Schwerpunktthema der tekom-Frühjahrstagung 2016 in Berlin: „Die Nutzer mit Intelligenter Information begeistern“. Der Keynote-Vortrag von  Prof. Wolfgang Henseler hat das Publikum davon überzeugt, dass um User Experience 4.0 zu erzielen, Produkte und Dienstleistungen “den Menschen befähigen und entlasten müssen, ihn aber nicht entmündigen!”

An beiden Konferenztagen durfte ich den Workshop “Einführung eines DITA-Pilot-Projekts – planen, starten, testen!” moderieren. Vielen Dank an den 50 Teilnehmern fürs Mitmachen und für ihren wertvollen Fragen und Feedback.

Es gab noch mehr aus der DITA-Welt in Berlin. Zum Beispiel: Dr. Sven Leukert von SAP hat die DITA-Spezialisierung und die üblichen Missverständnisse darüber erklärt; Jang Graat hat uns personalisierte Informationen mit Sahnehäubchen serviert.

Standbesucher und FCT-Team

Besucher und Berater am FCT-Messestand

Meine Kollegen von FCT AG, sowie unsere Partner von CCS Solutions haben sich über die Standbesucher in Berlin gefreut und sind schon gespannt auf die Jahrestagung in Stuttgart.

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!

Spice up Your DITA Workflows – Flashback tekomRS

by

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!

DITA is here to stay

by

or better said… to grow with us

It is seldom that I hear news about XML/DITA application in the DACH region (the German-speaking countries), so I was glad to attend the TIM Users Conference in Constance last week. TIM is the XML authoring and content management system developed by Fischer Computertechnik.

The two-day conference was indeed an intensive knowledge exchange between TIM users, the FCT team, and their partners. As I expected, most of the attendees and speakers are using TIM in manufacturing and machine building enterprises, as well as on-site support services. Adobe FrameMaker and Microsoft Word are still broadly used as editors, but it is encouraging to hear about well established German tools joining the DITA world.

Last year I was reading in the DITA community about concerns that the standard was not being supported enough in Germany, but I must say it does not look that bad to me. As long as DITA is on academic curricula and major conference programs, no one can say it’s being discouraged. New and well-known, local CMS providers are offering and promoting DITA modules. When corporations as large as SAP are adopting a standard, the rest of the world has to follow.

As Prof. Wolfgang Ziegler was saying at tekom 2013 in Wiesbaden during his talk about information portals, DITA and XML have been around for 20 years… we don’t even talk about reasons for doing XML anymore – we just do it! (“Macht man einfach!“)

Prof. Sissi Closs is also talking regularly about DITA and single sourcing. In Constance she was presenting DITA Information Architecture as a relatively new and absolutely necessary discipline, functioning as a continuous, agile process of information management.

Dr. Walter Fischer was declaring himself convinced by the advantages DITA brings to the technical communication, especially considering what the Internet of Things triggers in the emerging Industry 4.0 age.

In workshops, presentations, lightning talks, over coffee, football 😉 WM public viewing or on a boat trip on Lake Constance, “TIM-players” from Austria, Switzerland and Germany were in agreement: We need more collaboration with industry partners, when it comes to exchanging content and integrating tools. Partner content providers are hiding behind a copyright clause and would only send a PDF or a protected copy of an illustration, instead of sharing the sources with integrators of their products and documentation.

Machines are talking to machines and to humans, yet humans are still reluctant to comply to standards and to exchange information. XML is everywhere around us anyway, so why do we have to wait and be forced to switch at the last moment, when it’s obvious we need to work with a standard like DITA, to collaborate and manage information?

Darwin is in the DITA name for a reason: it’s an XML standard that’s evolving with us.

Happy DIT’ing!