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!

Be an XML writer and proud of it

Why am I scared every time I hear or read about “easy” or “light” tools and standards for tech writers? Do we really need to scream out for compassion? Is technical writing that complicated?

Assuming that tools are complex and distract us from the main task, meaning actual writing: How should we see our job? From what I see around and on the Web, the message seems to be: “I’m a writer, I have an English degree, so I just have to be creative, write freely, without restrictions from standards or tools.

Reality check: The customer is paying for an immediate solution to a problem, not for reading our best essay. The employers pay us to deliver accurate, readable, findable, and timely information. So, setting aside that creative writing is not necessarily informative, we are required to work by certain standards and with discipline. We have to contribute to the business objectives, not to the national literary patrimony… at least not during business hours.

As for the tools or code, why wouldn’t we prefer writing some XML tags to apply semantic structure to the information, instead of pressing some buttons to apply just styles and then spending more time on tweaking the layout than we did on writing the text?

If the target users and the business model need to find and exchange the content on various devices, so be it. We can support them.

Instead of writing in a word processor “Place the cup on the tray and press Coffee“, then selecting “Coffee” and applying some style from a list, we can just as easy, or maybe even quicker, write in a plain text or wiki editor “Place the cup on the tray and press *Coffee*“.

Even better, in a text or XML editor, we would write: “Place the cup on the tray and press <uicontrol>Coffee</uicontrol>.” Now Coffee has semantic meaning, and can be rendered in whatever way the customer needs it. Might be bold, might be brown, might even be hot and smell like coffee, why not?

And why should we be scared, if we’d have to write “Place the cup on the tray and press <uicontrol keyref="btn_hotbeverage">.” so it can be reused by colleagues, by business partners, or even by the entire community, if we’re acting in the crowd-source spirit of the Internet (of people and things)?

One small step for man…