Tag Archives: workflows

Content Strategies and the spirit of DITA

by

The mini-tracks during Content Strategies 2016/ DITA North America have shown DITA development in so many fields of content and communication:Washington Monument

  • Lightweight DITA
  • Taxonomy
  • Video
  • Translation
  • Learning and Training
  • Medical Industry
  • DITA for the Machine Industry

The spirit of DITA, as Michael Priestley reminded us in one of his presentations, is to ADAPT. The more options and tools are emerging, the more ways there are to connect and grow towards Enterprise Content Management, to consolidate, coordinate, collaborate on common content across departments.

From one track to the other, conference attendees could learn about minimal content models that “can still go crazy” (Michael Priestley), ditamaps handling decision points as a dynamic flow (Chris Nitchie), cross-format content in ditamaps (Carlos Evia), shaping the content with taxonomy (Joe Pairman), card-based content authoring and delivery (SAP), simple DITA format for translation (George Bina), augmented linguistic review (WhP).

To encourage even more teams to adopt DITA, I presented the model2dita project and was glad to see it struck a chord, just as it did last November at DITA Europe in Munich.

model2dita: Generate your DITA project structure from the information model

What is your process when you start a new documentation project in DITA? How do you decide on the content and by which magic does it turn into DITA topics and maps? To develop effective, user-oriented information, you should invest most of your time in researching your audience and in task analysis rather than clicking New > File > Map, New > File > Topic and dragging topicrefs…

New DITA writers often find it difficult to envision the transformation of the information outline to the actual DITA structure. Others don’t even have the habit of starting with an information model in the research phase of a project.

The prezi shows the importance of the modeling phase in the writing workflow, as well as some methods and tools for translating the model into a DITA project structure automatically.

Moreover, I owe a hat tip to Paul Zimmerman (CISCO) for mentioning my last year’s project, rst2dita, about markdown round-tripping in his presentation “Get to Gittin’ On: Integrating code and content management in Git“.

Touring Reston, VA and Washington, DC was remarkable. See you all again in Munich in November.

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!