Top 5 reasons I look forward to the STC12 Summit

I’ll be going to my first STC Summit in a couple of weeks and I’m already really excited about it. Here are my top 5 reasons and motivations:

1. Learn about new trends

The obvious reason to attend a conference: Many of the 80 sessions cover new industry trends – or at least topics that are new to me. We’re currently implementing a new HAT which brings a a lot of opportunities and some challenges, so I’m looking forward to:

2. Find inspiration and solutions

The sometimes unexpected benefit: At previous conferences, I frequently got ideas about improving a broken process or solving an irritating problem, even if that was not the main focus of a session. Such insights might come from an aside comment or something I see on a slide that inspires me to connect the dots. That’s why I’m looking forward to:

3. Present my own session

A highlight for will be Pattern Recognition for Technical Communicators!

My STC Summit speaker button

I’ll be on Wednesday morning at 8:30. I know that’ll be difficult after Tuesday’s banquet and whatever after-hours may transpire. But it’s actually a very good time!

  • A good time for you, because you can ease into the last day with an entertaining session that gives you a different, thought-provoking perspective on what you do anyway.
  • A good time for me, because I can get a feel for the conference on Monday and Tuesday and then get it out of the way firsrt thing on Wednesday. So I hope to see you there!

The conference program

After teasing you about several interesting sessions, here’s the complete conference program:

  • In a website, sortable by track, time, speaker or session code
  • In PDF, sorted by day and time, with session codes and titles only
  • In Excel 97-2003, sorted by day and time, with titles and main presenter

The first two are the official resources from the summit website, the spreadsheet is from me. All three are current as of May 6, but only the first one will be up to date in case of changes (an updated PDF may have a different link…). To be on the safe side, check the official summit website. – Now back to the reasons…

4. Meet old friends, make new friends

The pleasant side effect also called “networking”: As much as I enjoy social media as a virtual lifeline to stay in touch with the techcomm community, nothing beats meeting in person over a beer once or twice a year. So I’m looking forward to meeting speakers and delegates, tweeps and blog readers!

5. See Chicago

The tourist bit: I know Chicago a little bit from when I went to UW Madison in the 1990s. But I haven’t been in a while, and I’m especially looking forward to visiting the Art Institute and the new Modern Wing – or at least new to me. 🙂

6. Shop around for help authoring tools

Your bonus reason. The company I work for is not in the market right now for a new tool, but maybe you are. With more than 50 product and service providers exhibiting, you’ll have an excellent chance to see a lot of products up close and compare them closely. It’s a little like meeting friends: Nothing beats a first hands-on experience, and it’s a lot less daunting when you don’t have to install a trial version and click your way around. Vendor exhibitions at conferences were essential for us when we were choosing our tool.

7. Deep dish pizza

The gourmet reason. Thanks to Larry Kunz for the reminder, see his comment below. I was quite fond of Pizzeria Uno in my Madison days…

– If I forgot a reason to go to a conference, please share it below. If you’re attending the STC Summit, I hope to meet you in Chicago!

Advertisements

Linking topics: Cross-reference or relationship table?

Choose the appropriate reference type, cross-reference or relationship table, to link between topics so you and your readers get the most from your documentation.

When you’re moving from less-than-structured documentation to topic-based writing, one of the less apparent challenges is to link your related topics to one another. You could just keep on using cross-references, but then you’d miss out on some of the benefits of topics.

Whether you write topics using a standard like DITA or a tool such as MadCap Flare, you have a new cross-reference type, relationship tables. It is important to distinguish the two types, because each serves a unique purpose.

Cross-references

A cross-reference is the link you know from Word or other document-based writing: You create a link to a heading or a bookmark, it can show the heading title, and it updates automatically if that heading (or a page number) changes.

It leads readers from a certain point or condition to another place. It tells readers:

If you want to do or know that now, go over there.

So far, so good. This kind of link works well, if you have a document with an organised sequence. Occasionally, you need to offer the reader an occasional branching into two alternative secnarios or a jump to another place.

But when you convert your content into a pile of loosely connected topics, you have much more demand and more opportunities to relate topics.

Disadvantages of cross-references

Cross-references aren’t always the best way to relate topics because they:

  • Disrupt reading flow and orientation. For users, it’s fine to make the occasional choice between scenario A or B. But offering too many links will tempt many users to wonder what they’re missing at the other end. And following link after link from within one topic to the next quickly breaks the flow of tasks and leaves the user confused.
  • Create a web of dependencies. With cross-references, you tie your topics to one another in a certain preferred scenario you engineer. This scenario may not suit the user’s current need. It undermines the flexible “stand-alone” independence of topics that supports multiple use cases. And it makes it harder for writers to reuse them.

So while cross-references are easily a preferred way of linking contents in document-based writing, consider carefully how they will affect your use, and the users’ benefits, of your topics.

Cross-references in topics work well in these cases:

  • Link to mandatory pre-requisites or required next steps.
  • Link to a series of tasks in an overview/parent topic.

In either case, the user pretty much must follow the link to achieve anything useful, so cross-references are fine. Just make sure that the link and the surrounding text are meaningful, so users can decide whether they should follow the link.

– So if cross-references are not always recommended, how else can I link between topics?

Relationship tables

A relationship table is best to indicate that certain topics as a whole are related. It tells readers:

If you’re involved with this topic, you should also be aware of those topics.

For users, links from relationship tables appear separately, usually below the actual topic text in a section of related links or “see also”, depending on how you choose to style them.

For writers, under the hood, a relationship table is a separate file that lists by type which topics are related to one another. For example, I could have a table like this:

Concept topics Task topics Reference topics
Income taxes Calculate income taxes Income tax deadlines
File income taxes Addresses of tax offices

This means that the topics are related as a whole. And they will remain related, even if you update one of them by adding, changing or deleting a paragraph.

This is a pretty new concept if you’re used to writing long single documents. And it might feel awkward to have references outside and removed from the linked topics.

Advantages of relationship tables

Once you wrap your head around the idea, relationship tables have several advantages:

  • Keep your topic text flexible. With such a table, you don’t lock your topic into a certain scenario as a cross-reference does. A cross-reference establishes a fixed connection – which might be irrelevant or not even available for certain users or product versions. It’s much easier to drop a topic in a relationship table where it will not appear if it doesn’t exist for certain users or products.
  • Keep your references complete and up-to-date. With tables, it’s much easier to oversee the complete set of links and relationships than with cross-references inside topics. If you’ve ever tried to manually update and rephrase links to a new important topic which has replaced an obsolete topic in countless places, you will appreciate a table where you can simply add or omit any one topic.

Relationship tables are not superior to cross-references. They simply serve a different purpose. I hope this post helps you to appreciate the benefits of either type and to decide when to use which. Please leave a comment to let me know if I’ve succeeded or have been wrong or unclear somehow.

For more about converting documentation to topics, see previous posts about:

Concept or reference, what’s the difference?

The distinction between concepts and reference topics is much easier and clearer when both support strong and clear task topics.

Concept or reference?

One of the recurring difficulties when moving to structured writing and topic-based authoring is the distinction of topic types concept and reference. It’s an odd problem because the three topic types, concept, task and reference seem rather logical and clear-cut in theory.

I’ve found that the best remedy for the confusion is the motivation that lies beneath topic-based authoring: Task orientation. Think of it this way:

  • Task orientation is a design strategy for your documentation
  • Topic-based authoring is “only” the method to implement task orientation.

So concept topics and reference topics exist to support tasks. “The goal for users … is not to understand a concept but to complete a task.” (p. 41, DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA).

Let tasks lead the way

Much of the uncertainty whether a topic is a concept or a reference disappears, when you have strong, solid task topics in place. Topics that directly address your users and their daily tasks and help them to get their job done:

  • How do I create cool espresso drinks with my new coffee machine?
  • How do I clean the milk steamer?

Such tasks are the context in which the two definitions of concept and reference from the DITA 1.2 specification make sense:

  • Concepts “provide conceptual information to support the performance of tasks”.
  • Reference topics “provide for the separation of fact-based information from concepts and tasks”

Note that both definition recur to tasks, so task-orientation and tasks as above are at the heart of topic-based authoring.

To help readers understand the background to tasks, you can offer concepts about the kinds of espresso drinks there are and how they differ.

To support users to actually perform the tasks, you can offer reference topics with technical specifications such as required voltage and recommended water softness.

How to distinguish them?

If you’re in doubt in particular examples, maybe the table below can help you. I got some of the criteria from a Yahoo group discussion “Concept v Reference – Battle to the Death” and from a blog post on Dubious Prospects.

Concept topics Reference topics
Are abstract ideas Are specific settings
Explain meaning or benefit Give facts without much explanation
Can stay when specifications change Change with specifications
Support understanding of tasks Support correct execution of tasks
Are read for background information Are read for detailed information
“Why brushing your teeth is important” “Stages of tooth decay”

Half-way DITA: Why some is better than none

If DITA seems like a good idea, but you cannot make the case for it, you can move towards structured writing and make your documentation “future-proof” by meeting the standard half-way.

At the company I work for, we tech writers created manuals in parallel, but separate to online help. Over time, this gave us a documentation set that was inconsistent in places and hard to maintain to boot. Topic-based authoring which reuses topics in print and online can fix that, of course.

First, a documentation standard

Deciding on the method is one thing, but we also wanted a consistent structure that made the documentation easier and clearer to use – and easier to maintain for us writers. That required a model that specifies which kinds of topics we want to offer, how these topics are structured inside and how they relate to one another.

As we looked towards a documentation standard, we had two options:

  • We could create a content inventory of our documentation, analyse and segment it to tease some structure from that.
  • Or we could rely that others had solved a similar problem before and see if we can’t use the wheel someone else had already invented.

Turns out the second option was quite feasible: The DITA 1.2 specification gives us about all the structure we need – and more. We left out the parts we didn’t need (for example, some of the more intricate metadata for printed books) and adopted a kind of DITA 1.2 “light” as our information model.

Second, the tools

Note that I haven’t mentioned any systems or tools so far! Even though it happened in parallel to the rolling out topic-based authoring as our method and DITA light as our information model, the tool selection was mainly driven by our requirements on documentation workflows, structure, deliverables, and budget.

The tool that suited us best turned out to be MadCap Flare – even though it doesn’t create or validate DITA!

Using our information model in Flare, we believe we get most of the benefits of DITA – and considerable improvement over our less-than-structured legacy content. And speaking to people at WritersUA 2011, it seems that we’re not the only one to move from less-than-structured writing to XML and something “close to DITA”.

Technically, we’ve defined the DITA elements we need as divs in the Flare stylesheets, but otherwise use the straight Flare authoring-to-publishing workflow. Flare is agnostic to whether a topic complies with DITA, is somehow structured but not complying or totally unstructured.

The benefits of DITA, half-way

To us tech writers, the largest benefit of DITA, half-way, is that we can actually do it. We could not have gotten away with DITA, the full monty, which would have required a much longer project, a much bigger migration effort and hence, uncertain ROI.

For new topics, we are committed to writing them structured, so they follow the information model. To migrate legacy topics, we’ll have to ensure they have an identifiable topic type and a suitable heading, but we can cleaning up their insides in a “soft fade”, moving them towards structure one by one. This gives us a quicker win than cleaning up literally thousands of topics before having anything to show in the new method, model or system.

So we will have been working in Flare and with our home-grown information model for a long while, before all topics actually comply with the model. But then we will have a documentation set which we can feasibly move into real structure, whether we opt for DITA or some other XML-based CMS, with or without a CMS.

This post is an elaboration of a comment thread on the “Why DITA?” guest post on Keith Soltys’ Core Dump 2.0 blog.

Tech comm trends 2012, mashed up and commented

2012 is the year when tech comm’ers need to understand business processes and align documentation with new technologies, say tech comm pundits – and yours truly.

What I expect for 2012

Tech comm’ers need to understand business processes.

Okay, so this trend is not exactly new, but I expect it will gain traction this year. Scott Abel thinks so, too. Business processes are crucial for us tech writers in more ways than we might think. Ideally, we understand them in three domains:

  • In tech comm, we need to understand business processes to do our job efficiently, to improve how we work and to measure if (or prove when) we are understaffed.
  • In our employer’s business (or whoever has ordered the documentation we provide), we need to understand processes to contribute to the bottom line and to get out of the cost center corner.
  • In our customer’s business (or whoever uses the documentation we provide), we need to understand processes to ensure these customers or users are efficient and happy with both, the product we describe and the documentation we create.

In a nutshell: We need to know business processes, so we know which are the right things to do, whether it’s moving our documentation to a CMS, aligning our deliverables with the corporate content strategy, or updating our personas. At the same time, we need to hang on to our tech comm skills, so we know how to do things right.

What others expect for 2012

Here are two trends predicted by Sarah O’Keefe and Connie Giordano that resonated with me. (And I recommend you follow the links to get the experts’ predictions first hand!)

Creating documentation moves to the cloud.

Documentation will follow other content production to the cloud, such as collaborative Google Docs, blogs, and wikis. With this trend, I’m wondering:

  • Compelling event? Will cloud-based tech comm creation take off now – or do we need a more compelling event than ubiquitous access and the (alleged) lower operational costs?
  • Whose market? Will conventional HAT vendors be the major players, so their customers can keep their sources and move them to the cloud – or will HAT vendors (and tech comm’ers sources) be disrupted by other providers?

Documentation design aligns with mobile UX.

Tri-pane web sites are too large for effective user assistance on mobile devices which require new, condensed documentation designs. These will in turn feed back into other documentation formats. Here, I’m wondering:

  • Turf wars? Will tech comm’ers and UX designers engage in turf wars – or pool their skills and resources for better user assistance?
  • Innovation? Will the reduced real estate lead to genuinely new ways of presenting user assistance – or to a resurgence of minimalism?

What no one expects for 2012

The survival of the classical tech comm job profile

Virtually all tech comm predictions and trends for 2012 are driven by external forces of change: The cloud, mobile devices, or new social media habits which expect collaborative documentation and user-generated content.

At the same time, the trends and predictions I’ve seen show little initiative to define or advance technical communications as a profession around a set of skills and tools, methods and processes. The classical tech comm job profile (as described in the Occupational Outlook Handbook by the U.S. Bureau of Labor Statistics, for example) that is centered around deliverables and tools, formats and styles seems to wane.

In many sectors, technical communications has instead become a function that contributes to corporate assets and the bottom line. Technical communicators provide it, as do content strategists, information architects or UX designers. And whoever pays them doesn’t necessarily care who does it – or even know the difference.

In a way, this is the other side of the coin of the trends above. Scott Abel points out:

The real value we provide is not our mastery of the style guide. Rather, it’s our ability to impact the customer experience in positive ways.

And Connie Giordano calls for the evolution of “integrated technical communications” to coordinate and integrate

all technical communication processes, tools, functions, and sources within an organization to convey information and knowledge relevant to optimizing the users’ product experience.

So I believe technical communications is here to stay – but we may have to look for news ways of selling what we do and deliver.

What do you expect for 2012?

Will you follow the trends above? Are there others in your future? Please join the discussion, leave a comment.

5 steps from legacy documentation to topics

To move to topic-based authoring, you need to convert existing documentation into topics. The efforts shouldn’t be underestimated, but it’s actually a pretty straightforward process. I’m describing how to convert sections in manuals, but it’s much the same for most content, whether it’s FAQs, wiki articles, training materials, etc.

Prerequisites

  • Some knowledge of topic-based authoring. You should know the topic types you will use, for example, concepts, tasks and reference topics.
  • Have a tactical framework. Ensure you know the documentation structure you aim for and how you will get there in a project. Consider for example the Top 4 tactics to structure legacy documentation.
  • A style guide to which your documentation complies definitely helps.

1. Identify topic type(s) per section

Define each section in your manual as one of your topic types, for example, concept, task or reference.

If topic types are mixed…

A common problem at this point is that you may have topics that mix topic types. For example, your topic contains concept information and task information. Or task information and reference information. For details, see When topics don’t quite work.

2. Re-chunk sections to make them topics

Redistribute your content so each section becomes a topic:

  1. Cut out everything in a section that doesn’t fit the selected topic type and put it aside.
  2. Ensure that the topic that remains:
    • Is either a concept or a task or a reference.
    • Presents only one idea.
    • Has only one purpose.
    • Can stand alone, in context with others.
  3. Take the content you have cut out and put aside and do one of the following:
    • Integrate it into an existing topic where it fits better.
    • Create a new topic for it.
    • If it’s not relevant, throw it away. 🙂

If topics are too complex…

A common problem at this point is that you can end up with one or several topics that are too complex. Then you can try the following:

  • If you can describe a topic’s content as two separate, but related ideas, turn it into two sibling topics.
  • If you can fully summarise a topic’s content only as a very complex idea, turn it into a parent topic and create children topics for it.
  • If it’s a long procedure with more than 10 main steps in a top-level numbered list, try to cut it into two topics approximately in the middle.

3. Re-sequence your topics

Re-arrange the sequence of your topics, so they flow nicely when users read not just one or two of them, but need to learn a complete setup or operational process.

  1. Verify that your topics are in the best possible sequence and re-arrange them if necessary. You might want to try these categories:
    • Setup, in the sequence of tasks.
    • Operations, in the sequence of tasks.
    • Reference topics, in alphabetical order.
    • Concept topics can either appear as a section of their own, ordered from the large/general to the small/particular, or among the other topics as appropriate.
  2. Verify that your topics are complete and add topics, if necessary:
    • Do you have concept topics for all major elements in your task topics which explain what these elements are?
    • Do you have task topics for all concept topics which explain how to set up and operate the elements

If the topic sequence doesn’t flow nicely…

A common problem is that the topics don’t flow as nicely once you have chunked them into stand-alone pieces. In this case, add some “glue” topics which orient readers and ensure a good flow, for example, at the beginning of chapters in books. Consider including these glue topics only in print deliverables; maybe they are not necessary in your online help.

4. Rewrite headings to guide readers

Often your legacy section headings work in the context of your manual, but don’t give users enough orientation when they read just one or two topics. Rephrase them so users can quickly dip in and out of your documentation. Keep these guidelines in mind:

  • Reflect the user’s need or goal in the heading.
  • Phrase headings so users know what’s in the topic when they see only the heading in a link in another topic.
  • Try to make headings unique so there’s no confusion when they appear in search result lists.

5. Add links between related topics

Ensure that your topics have links or cross-references between all related topics:

  • Do your concept topics link to corresponding task topics – and vice versa?
  • Do your task topics include or link to prerequisites and next steps?
  • Do your task topics link to corresponding reference topics?

Your turn

Do you find these steps helpful? Have you converted documentation into topics before? Please leave a comment.

Top 4 tactics to structure legacy documentation

The success of a move to topic-based authoring and/or structured writing depends on the order of your steps – and good planning is key. You can’t make it up as you go along.

The Company I Work For is moving its extensive user documentation to topic-based authoring and a DITA-compliant information model. That requires converting existing documentation, such as user manuals.

Many current manuals are like tutorials: They guide readers by example with lots of screenshots. They are easy to follow along, but more difficult when you need to know about individual procedures or about scenarios which don’t match the example.

I’m currently converting and restructuring some of these user manuals into topics. Basically, I’m taking them apart and reconstructing them into concept topics, procedure topics and reference information.

Here are some lessons we learned in the process:

1. Define the structure first.

Even if it takes a week or two, be sure you have 80, 90% of your structure in place before you start tearing up contents to convert them. If you simply make it up as you go along, you’ll get an abstraction of whatever content you start with – which most likely won’t suit all of your contents.

You’ll be better off, if you at least sketch out the common topic types such as concepts, procedures and reference and define what goes into them in which order.

For example, procedure topics could contain

  1. One or two intro/context paragraphs
  2. Prerequisites (if any)
  3. Procedure as a list of numbered steps
  4. Expected results
  5. Exception handling (if possible and applicable)

2. Carefully select pilot projects.

Start by converting content that is both typical and mainstream. This way, you can validate your structure and discover gaps or errors.

This also makes it easier to show progress and reap some quick wins. You can give managers and colleagues something tangible what the future documentation will look like to ensure confidence and support on your path.

3. Draft the new topic structure.

Use the defined structure to draft a specific structure for the content you’re about to convert. Just leafing through the pages of a manual will give you a pretty good idea which topics you will be able to create from it.

Order all those topics into a structure, so you have sort of a table of contents for the new topic-based manual before you begin. This structure need not be set in stone, if you find you need to arrange or add topics, but it should present a sensible picture.

Ensure, for example, that procedural topics are backed up sufficiently by concept topics so we have room to explain the “what” before you explain the “how-to”. Or, if you have both setup procedures and operational procedures, ensure that setup corresponds to operations.

4. Proceed along the old content.

In the actual conversion process of chunking text, moving it into the new structure and rewriting it, follow along the old structure. That will create a temporary mess in your new structure where you may find yourself dumping random paragraphs and sentences under headings.

But this allows you to cross off section by section in the old manual with the confidence that you have moved it over. This is much faster and more reliable than constantly going back to the old manual, worrying if you’ve left anything behind.

Your turn

Do you find these tactics helpful? What experiences have you had when converting legacy content into structured documentation? Feel free to leave a comment.