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…

Integration der Produktinformationen bevor 4.0

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

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:

IA and TechComm at EUROIA14

Continuing my flashback notes, after Brighton and Bucharest, let me take you to the third B-named city I had visited within a month: Brussels. I finally managed to attend EUROIA, the Information Architecture conference in Europe last September. They closed the 10-year loop back in Brussels and I joined just in time to celebrate and received a cool anniversary T-shirt.

This was quite a change from the usual techcomm conferences. In my “scrapcloud” attempt I mentioned only a few of the terms that stuck with me from EUROIA14, but it was so much more. It took me to the… “liminal”-zone 🙂

EUROIA14 scrapcloud

We were shown the artistic side of information architecture through presentations about design, architecture, innovation, anthropology and psychology. But in the same time, workshops and presentations confirmed that info architects and user experience designers are facing similar challenges technical communicators do. Lots of familiar images: spreadsheets for content auditing, models to sort, chunk and reuse information. One page per thing was an often mentioned rule, as well as MRUs (minimum reusable units). Ontologies and linking are of course vital, since they are the very mechanism that keeps the web running. Does CORE model sound familiar to tech writers yet? It should: Create Once, Reuse Everywhere. And the statement that probably got just as much ovation and Twitter coverage as the marriage proposal in the end, was the reminder that Content is f*** King!

What also seemed a déjà vu, was the effort of info architects to establish their role and responsibilities within companies and workflows. we are all in the center

After seeing in various projects and books those diagrams with all team members or skills in their little circles, all pointing to the project manager (call it scrum master if you will) in the center, then seeing the same in slides trying to define the technical writers’ job and how they should position themselves and communicate with all other roles in their projects… it was the IA and UX designers’ turn to flip the charts.

Good to know we’re not alone and interesting to see we are trying to connect with the same roles in our projects: managers, developers, engineers, testers, etc.

Can hardly wait for the next EUROIA and I hope to see some more conferences adopting their agenda model:  workshops every morning, presentations and lightning talks in the afternoon, dozens of books to give away each evening.

Have you planned for content rebranding?

As a tech writer, you get used to a number of changes along the years, like migration to new standards and tools, company and product renaming, rebranding, merger and takeover, localising for a new language or region. Such changes affect the entire organisation. The decision comes from above and it is seen as a top-down process, so unfortunatelly not all departments get a share of the attention.

Usually, a new styleguide is announced, along with launching a new website, mission statement and promotional materials. When it finally comes, you browse through the new guide, eager to see what the new image and vision of the company is, and how this change is going to apply to your work. Alas, the new guide mostly contains instructions for Sales, Marketing and Web.

I have so rarely seen a plan to identify and analyse the content across an organisation, before a rebranding and renaming endeavor takes place. Only after the new look has been decided and dictated, teams such as Support and Documentation are asked to commit to a deadline for making the changes in their content. The fact that the products themselves (meaning Development and Localisation) would also need to plan some changes, often comes as a surprise too, and they have to start hunting for the sources of phantom bannners and messages in the last minute.

Some companies are fortunate enough to have conscientious teams, who try to prepare ahead when hearing about big changes. They think of their content inventory and determine which parts of it would actually need to be updated, translated or restyled, thus even saving their company some time and money. They would be ready to commit to the change and all they’d need would be the new styleguide.

The surprise is, even after asking to make sure the guide would contain the styling needed by the Documentation and other teams, you wouldn’t find anything more in it, than the specifications for the logo, new colour scheme and maybe some PDF cover samples. Everything else is for marketing materials, website, MS Word and PowerPoint templates.

How about the styles and layout of the Knowledge Base, FAQ portal, Manuals or User Guides, Help files, Data Sheets and Specifications, API Reference, user forum, tester portals, etc.?

Not only are the users going to wonder whether the content belongs to the same company, when facing most of the Support and Documentation materials, but also why it still looks and feels so like… last century.

How do you reuse paragraphs?

Die Qual der Wahl“… it’s hard to choose, sometimes. There are many ways to apply reuse in DITA, or in other authoring environments. What would be the best way for a team to manage reused content, in case of similar topics with series of list items, table rows or just paragraphs?

The usual discourse in lectures, books and webinars I’ve seen, although using various names, compares methods like inclusion (referencing, insets) and conditioning.

Two reuse methods

To achieve the same results (publishing deliverables A, B, C), you can work with methods such as:

  • managing a warehouse topic, from where each author retrieves components by ID (conref or conkeyref, in DITA) and maintains individual topics for each project.
  • managing one common topic for all authors and applying conditions (attributes) on items specific to each project.

The first method obviously adds one intermediate stage, requiring each author to maintain parallel versions of the same topic. Apart from that, it depends on your policy, if you would see it as an advantage, that the authors can rearrange the items and even add extra content around them.

Although the second method brings the advantage of maintaining only one source, it adds more complexity at taxonomy level. The combinations of attribute values and the number of ditaval files or entries in the subject scheme map can become overwhelming.

There are other possibilities, of course. For example, to consider topic1.xml the master topic and to work with topic2.xml and topic3.xml as variants of 1, which means changes in topic1 would also influence the variant topics.

Thank you for your input.

Is structure about code or about content?

Here’s a short one, cause I’m writing on a train to Nuremberg…

When writers are not used to structured authoring and have to adopt a standard like DITA, they tend to blame DITA and the new tools for complicating their lives. In the new process, the first thing writers notice is that they have to use elements they are not familiar with, and that there are various ways to use them.

Unless they go through training on structured authoring, they start with the wrong plan, that the unstructured text (and thinking) would just have to be mapped to the new structure, as “structure” would be about code, not about writing.

Indeed, the XML code sets a valid structure to the topics, but there is more to structure than applying DITA elements. Documentation can benefit from the principles of structured authoring even without adopting a certain standard. You can do your project research and information model, define your own house rules and styles, to provide consistent, minimalistic, reusable documentation, in almost any authoring environment.

Do not blame DITA or the tools, that you have to structure your procedures or your lists of parameters in a certain way. Ideally, you would have seen the need for that structure before, and thanked Heaven (or the DITA committee) when the standard came and you rushed with the business case to your team and managers.

Happy DIT’ing!