Building a DITA pilot project

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.


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

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:

DITA Pilots, on your marks…

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.
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:

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.

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 😉

DITA Linking Best Practice

Join us (Jang & Magda) for a day’s Master Class on DITA Linking Best Practice at Information Energy 2015

As users of technical information (in a manual, in embedded help or on the web), we use links all the time. Sometimes they lead to the exact topic we need and sometimes we end up running around in a wild goose chase.

So how do you make sure that your users find their information quickly and easily? By setting up the right linking strategy for your product and your business domain. This sounds easier than it might be, as there are various linking strategies and not one of them is the best in all possible situations.

This master class teaches you about the available link management strategies in DITA and gives you a sound basis to decide which strategy works best for your information products.

We’ll explore the various types of linking with hands-on exercises:

  • Element-level linking: linking to graphics, tables, steps, files.
  • Hierarchy linking: links generated by nesting, family collections, sequences.
  • Relationship tables: bidirectional links, uni-directional links, collections.
  • Subject-scheme maps: taxonomy and topic assignment.

Each section starts with a conceptual overview and a set of practical tips and tricks, followed by hands-on work using your own set of DITA topics and maps on your own computer. Each practical session ends with a group session in which you exchange experiences and learn from each other.

After attending this workshop, you will be able to choose a linking strategy that fits your information products like a glove.

Date: June 2, 2015
Time: 10:00 – 16:00
Location: Academiegebouw, Utrecht
Language: English
Costs: €395, including lunch and drinks (Early Bird: €295)

Register for the Master Class “DITA Linking Best Practice

Related links:
Information Energy 2015
JANG Communication