Category Archives: Technical Writing

Happy DITA in Germany

by

Deutsche Version >> Auf ein glückliches DITA Jahr!

The last months of 2015 have been quite tumultuous and there is a lot I’ve been meaning to share with you. I’ll catch up with the posts in January, but the most important message to start 2016 is: DITA is here to stay! I’ve said it some time ago and I say it again, because there is growing interest for DITA in Germany, as numerous presentations, workshops and panels proved once more in November at tcworld and DITA Europe. The community is taking shape, tools and systems start supporting DITA and the discussion is, well, passionate, to say the least.

Back in September, I was a bit disappointed and worried… for about five minutes 😉 as an anti-DITA “whitepaper” had been published by a group of German CMS providers. They also took some poorly founded slides meant to discourage DITA implementations on a roadshow through Europe. But as I read the material and tried to see beyond the tragi-comical dark force awakening (or FUD, as Americans name such attitudes: fear, uncertainty and doubt) I decided to ignore them and just concentrate on my commitment to support DITA adoption in Europe, especially in the German-speaking community, and each of you is welcome to contribute.

It is absolutely normal to face resistance to change and no expert would ever claim DITA was the best answer to every type of technical communication projects. However, if DITA fits the requirements and audit findings, professional consultants and system providers have to respect their customers’ business decisions and prove capable of change, instead of sending an arrogant, self-destructive message like “it’s how we’ve been doing it over here for twenty years, so we don’t see fit to change.”

DITA experts and fans attending tcworld in Stuttgart, myself included, were reporting on social media about lots of interesting sessions, but also about a few misleading ones during the conference and shortly afterwards. They patiently and, unlike some “anti-DITA hosts”, politely commented on the misunderstandings.

I could write yet another review and provide lists of links to those discussions, but my feeling is: enough is enough! We should let such disputes aside. The competition between standards or CMSes should be healthy, maintaining a well-balanced market. We should all concentrate on the benefits for end-users and authors, instead of attempting negative awareness tricks. As consultants and tool providers, whether we work more with DITA, PI-Mod, or other grammars (I’ve also studied and worked with more of them), we should be proactive and show what we can do best for our customers and partners.

My message to the technical authors and content managers is: It is your team’s decision, never a system provider’s, what standards you choose to adopt, in Germany or elsewhere. Keep your eyes on the developments and requirements in user assistance and make informed decisions on your technical information. Involve your teams, test and select the tools that help you reach your business goals.

Thank you all for a wonderful 2015. Have a successful 2016 and keep your teams, customers, and end-users happy!

Building a DITA pilot project

by

The DITA pilots were hard at work again at TCUK. We have discussed what changes may come with the DITA implementation, but also what should stay the same… if done properly, namely the research and planing phase of a documentation project. The four working groups designed personas and use cases for a specific product line, then drafted the documentation outline that formed the basis of their DITA project.

ditapilots

You can see the prezi I used for the first part of the workshop here:

workshop prezi

Click the image to open the Prezi slideshow

Once we had a documentation outline, we started a DITA skeleton project in oXygen XML Editor. It is called a skeleton project, because we started a simple ditamap, just by replicating the outline, without actually creating any topics. We just added symbolic topicref elements and inserted the titles from our outline in navtitle attributes. A skeleton map can even be published for review.

Thus the writers have the entire outline model in the ditamap from the beginning and would be ready to start creating topics and developing the content using the ditamap as guidance, then adding the actual topics to the map in href attributes. This approach can be applied not only to provide orientation while creating new topics and enhancing the model, but also to ensure consistency across documentation sets… at least until fancier project templates are in place.

In case you’d like to try out building a DITA skeleton project, you can download the tutorial as PDF file ico_PDF.

Happy DIT’ing! More entertaining TCUK keepsake from Glasgow coming soon.

Upcoming workshop: Building a DITA pilot project

by

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…

Integration der Produktinformationen bevor 4.0

by

SchiffahrtMitte Juni fand die TIM Anwenderkonferenz in Konstanz statt – erneut eine großartige Gelegenheit, sich mit Kollegen aus der Technischen Redaktion und Engineueren der Service-Abteilungen aus dem deutschsprachigen Raum in einem historischen Resort am Bodensee zu treffen und auszutauschen.

Als Titel auf dem Programmheft stand allerdings ein Satz, der mich unruhig machte: “Jede Information zu jeder Zeit an jedem Ort”. Ich vermute mal, dass es mit den Vorträgen über Modernes Content Delivery, Produktkommunikation 4.0 und Praxiseinblicke in Industrie 4.0 zu tun hatte, scheinte aber die Ziele und Bemühungen in den letzten paar Jahren in unserem Beruf zu widersprechen – “Als technische Redakteure, liefern wir die richtige Information zu richtiger Zeit an richtigem Ort.”

Klar müsste man sich als technische(r) Redateur(in) mit Themen wie Internet of Things (in diesem Kontext, Industrie 4.0) und Omnichannel Content schon beschäftigen. Es heißt aber lange nicht, dass nur weil man heutzutage die Technik dazu hat, sollte jedes Datum oder jede Information gesammelt und gepflegt sein. Ohne genaue Geschäftsziele und ohne die Analyse der Zielgruppen-Tätigkeit und -Kanäle, gibt es keine Strategie für die Doku 4.0.

Die meisten Konferenzen und Seminaren werden im Moment zu Industrie 4.0 gewidmet. Nichtsdestotrotz scheint es kein gemeinsames Verständnis darüber zu geben, außer die Referenten sagen immer “Sie müssen es tun. Denken Sie an die vielen Möglichkeiten.” Meiner Meinung nach, braucht die 4.0-Technologie (und die 4.0-Redakteure) im Industriebereich noch ein bisschen Zeit zu wachsen, damit die Umgebung aufholen kann. Es gibt zwar die Software und Hardware, Unmänge an Daten zu sammeln, sowie teilweise Algorythmen zur Analyse dieser Daten, jedoch fehlen die (standardisierten) Schnittstellen und Benutzeroberflächen, um die Ergebnisse visuell lesbar zu machen und Entscheidungen im Industriebereich zu unterstützen.

Mittlerweile in der realen Welt, wie mir manche Experten und Redakteure in Konstanz berichteten, kämpfen sich die Redakteure noch durch, wenn es um die einfache Integration von ihrem Content Management System mit SAP oder anderen ERP-Systemen geht. Sie müssen immer noch die Metadaten manuell doppelt eingeben, weil die Systeme und bestimmt auch die verantwortlichen Personen nicht miteinander kommunizieren.

Apropos verantwortlich, finde ich immer gefährlich, dass die Redakteure und nicht Produktentwickler für die technischen Daten in CMS und für die Metadaten in ERP Verantwortung tragen sollen. Diese Daten sollten automatisch zwischen Systemen synchronisiert werden. So würden die technischen Daten und Änderungen die Redakteuren nicht kümmern, genauso wenig wie Engineure für Metadaten Sorgen tragen würden. Jedes Datum soll man nur einmal eintragen und an einer einzigen Stelle pflegen. Information Chain word-cloud

Meine Word-Cloud Notizen zum Vortrag über “Information Supply Chain Management” zeigen einen weiteren und bekannten Grund für die Integration der Produktinformationen – die multidimensionale Welt der Informationen im Unternehmen, die von der Arten, Systemen, Rollen und Prozessen während des Lebenszyklus gegeben wird.

Es gibt noch jede Menge Arbeit, die Informationsprozesse zu optimieren und zu integrieren, bevor Produktinformation 4.0 geschehen kann.

[Update:] Es sind mir noch ein paar Artikel in der Presse aufgefallen:

DITA trends from Chicago

by

The Spring trend at Content Management Strategies/ DITA North America in Chicago has been “markdown-to-DITA”. Many sessions have touched the subject and echoed on social media.
Chicago-April2015
The talk about markdown was opened by George Bina and Radu Coravu. If you haven’t seen the DITA Glass project from SyncroSoft yet, you’d better catch up. They showed how MS Office documents, HTML, markdown, javadocs, PDF are transformed using a Java URL handler into virtual DITA topics. Jarno Elovirta had also released the DITA-OT Markdown plug-in, transforming markdown to DITA topics when generating output.

The debate about content round-tripping is still open. As Jang Graat was demonstrating and even impressing some writers to tears (I kid you not) with his Live DITA project, it may be that techcomm teams do not have to follow the software development workflow after all.

My humble contribution was the rST2DITA round-trip in the Emerging Technologies Track.

“Let’s take one more step towards breaking the silos: With simple XSLT transformations of rST in-line code documentation, you can integrate it with the rest of the DITA topics. Allow writers to edit the documentation in their DITA editor, generate the output and store the sources in the repository. To share the updated sources with developers, do the round-trip between DITA and rST formats, and store the rST version back in the code repository. This method allows developers to keep writing in their favourite environment, yet stay in sync with the rest of the product documentation.”

rst2dita cover

Click the image to open the Prezi slideshow

Upon seeing DITA Glass, my immediate thought was: it makes content crystal clear 🙂 Well… at least for engines. oXygen helps integrating non-DITA resources, giving speed and findabilility to our publications, but it’s  still our role as writers to develop clear, usable and context-relevant content, right?

Might virtual DITA be a workaround, until properly implementing an Enterprise Content Strategy?

Related links: