Unknown's avatar

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.

Unknown's avatar

Is structure about code or about content?

by

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!

Unknown's avatar

My DITA backlog

by

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”?

Unknown's avatar

The DITA Architect’s role

by

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!

Unknown's avatar

Be an XML writer and proud of it

by

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…