Tag Archives: reuse

IA and TechComm at EUROIA14

by

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.

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!

How do you reuse paragraphs?

by

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