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

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!

My DITA backlog

lists collage

Are you the list type? I know I am. I have all kinds of lists with things to do. I use Post-Its, note-books, cards, envelopes, apps, email tags… whatever comes in handy when the muse strikes, so every once in a while I need to aggregate the lists, categorize and check priorities.

It feels good when I can draw a checkmark next to a method or tool I tried, a book I read, a webinar, a workshop or conference I attended, but my DITA list is never shorter. Could be that I’m a DITAholic.

I’m surrounded by notes with things I have to research and try out in DITA, and while I try one thing, I think of two or three further issues to add to the backlog.

What’s your “DITA diet”?

The DITA Architect’s role

What does it take to be your team’s DITA Architect? Naturally, you have to thinkDITA, understand Information Architecture, use DITA for some time and know what you can do with it.

If in addition to being a DITA Author, you find yourself addicted to it, like there were no other way to do technical communication, if you read and try out all ideas you can find about DITA and related tools, then… you’re on the right path to being a DITA Architect.

There is one more thing, though. As I learned from Eliot Kimber (@drmacro), there is a difference between a geek and a nerd: the geek likes to talk about his nerdiness.

If you’re serious about the Architect role, you know it’s not enough to set up the authoring environment for the Writers in your team, especially if they are new to DITA. Apart from someone dealing with tools configuration, XML, XSLT, XSL-FO, CSS, jQuerries and Ant scripts for them, what the team needs, is answers to their questions, assistance, guidelines, code reviews, and even more answers.

You may thinkDITA and breathe DITA, but as an Architect, you have to lead and inspire DITA.

Happy DIT’ing!