Structured topics, taxonomies & lightning at #STC14

More than 600 technical communicators met for the annual STC Summit in Phoenix, AZ, to demonstrate and expand the many ways in which they add value for users, clients, and employers. In a series of posts, I describe my personal Summit highlights and insights that resonated with me.

The journey to structured topics

I’ve framed my presentation “From Unstructured Documentation to Structured Topics” as a journey to a fjord precipice: Daunting, but nothing you cannot achieve with a some planning and a little bit of confidence.

The summary outline during Q&A, photo by @dccd.

In this “project walk-through mini-workshop”, I outlined how we can combine core tech comm proficiency, such as topic-based authoring, with content strategy and project management skills to master the migration to structured topics. The applied skills and the resulting content architecture can be a solid foundation for a full-blown future corporate content strategy that highlights technical communicators and their skills.

The engaged Q&A afterwards showed that the ideas resonated with the 80+ attendees. Many technical communicators are comfortable and well qualified to expand their topic-writing skills into information architectures and content modelling.

The trip to taxonomy

In her session “How to Create and Use a Functional Taxonomy“, Mollye Barrett told of a similar challenge: She was originally brought in to create the documentation for a highly customised implementation of financial software. When it became apparent that not just the software needed documentation, but also the workflows and processes which it was supposed to support, she wound up creating a taxonomy!

As she laid out her case study, Mollye showed how technical communicators’ core skills of task analysis and task-oriented documentation qualify them to create a taxonomy of business functions that maps a software’s functions to specific user tasks.

The project essentially consisted of explicating the company’s multi-faceted tacit knowledge and connecting all the pieces:

• Create a consistent terminology by defining the standard financial terms in use.
• Describe and classify the various functions of the software.
• Identify and describe the users tasks which need documentation.

Mollye studied disparate, unstructured legacy documents, examined the software, and worked with specialists from the business and IT sides. Her main driver was her persistence to eliminate ambiguity, her goal to define clear terms – or put more simply: to create order out of chaos.

Lightning strikes twice

A popular staple of the STC Summit is the two lightning talk rounds, moderated with understated wit by Rhyne Armstrong.

Liz Herman drove forward the multi-skilled tech comm theme with multiple costume changes in her talk “Perfecting the Hat Trick, Why My Hair’s Messy“. She demonstrated how tech comm’ers don the hats, caps, and helmets of sailors, fire fighters, cowboys, football players, the Irish, something I’ve forgotten and many more in just five minutes:

Liz Herman dons diferent hats, photo by @dccd.

And Viqui Dill showed us how to use social media right in “Social Media is not the Devil“, her rousing karaoke performance to the tune of Charlie Daniels’ “The Devil Went Down to Georgia”:

Photo by @marciarjohnston.

 

Advertisement

Skill map, wicked ambiguity & influence at #STC14

More than 600 technical communicators met for the annual STC Summit in Phoenix, AZ, to demonstrate and expand the many ways in which they add value for users, clients, and employers. It almost sounds like a non-theme for a conference, but that was a common impression I took away time and again, prompted by my personal selection of sessions, no doubt!

This thrust is actually very much in line with the STC’s revamped mission statement (scroll down a bit) which includes these objectives:

• [Support] technical communication professionals to succeed in today’s workforce and to grow into related career fields
• Define and publicize the economic contribution of technical communication practices […]
• Technical communication training fosters in practitioners habits […] that underpin their ability to successfully perform in many fields

I’ll describe my personal Summit highlights and insights that resonated with me. For the mother of all STC Summit blogging, visit Sarah Maddox’ blog with a summary post which links to posts about no fewer than 10 individual sessions!

Connecting across silos with diverse skills

A good illustration for how easily tech comm skills and tasks connect with and seep into other job roles is Red Gate Software’s Technical Communication Skills Map. It appeared at least twice at the STC Summit: In STC CEO Chris Lyons’ opening remarks and again in Ben Woelk’s lightning talk.

Depending on a tech comm’ers talents and tasks, he can collaborate closely with – or develop into – a product manager or project manager, a UX specialist or tester.

Standing united against “wicked ambiguity”

Jonathon Colman, content strategist at Facebook, took a very high-level view of our profession’s challenges in his keynote address on Sunday evening. Technical communication that travels millions of miles on NASA’s Voyager or that must last thousands of years unites us against ambiguity – regardless of our different skills and various everyday tasks.

Such ambiguity can become “wicked” in fields such as urban planning and climate change, because it makes the issue to be described hard to define and hard to fix with limited time and resources. The solutions, such as they exist, are expensive and hard to scope and to test. Still we must at least attempt to describe a solution, for example, for nuclear waste: Tech comm must warn people to avoid any contact in a message that is recognizable and comprehensible for at least 10,000 years.

Jonathon ended on the hopeful note that tech comm’ers can acknowledge wicked ambiguity, unite against it, race towards it, embrace it – and try the best we can.

Wielding the informal power of influence

Skills are not always enough to connect us tech comm’ers successfully with other teams and departments. Sometimes, adverse objectives or incentives get in the way. Then we need to wield the informal power of influence. Kevin Lim from Google showed us how with witty, dry understatement – a poignant exercise of persuasion without resorting to rhetorical pyrotechnics.

Influence, Kevin explained, is the “dark matter of project management” that allows us to gain cooperation with others. We can acquire this informal power by authentically engaging colleagues with our skills and practices. (The “authenticity” is important to distinguish influence from sheer manipulation.) To optimize our chances for successful influence, we need to align our engagement with the company culture, a corporate strategy, and the objectives of key people, esp. project managers and our boss.

Put everything under a common goal and engage: “Don’t have lunch by yourself. Bad writer, bad!” – appropriate advice for the Summit, too!

– Watch this space for more STC14 coverage coming soon!

Preview my STC14 session about structured topics

If you are curious about moving from unstructured documentation to structured topics – or if you cannot decide whether my session at the STC Summit next week is for you – here are the slides, maybe you find them helpful:

Kai Weber – Unstructured documentation to structured topics – stc 140519 – public

Moving to topics? Join me at STC Summit!

If you’re moving to topic-based authoring (or considering the move), join me next week at the STC Summit in Phoenix for my presentation “From Unstructured Documentation to Structured Topics“.

The format will be a “project walk-through mini-workshop” in a regular session slot of 45 minutes. That means you won’t get a detailed project plan or silver bullet for a successful migration to topics. But you will get plenty of information about the involved methods, options, and risks. Most importantly, you will get a chance to improve your confidence – and hence your chances for success – for such an important project!

Here’s the abstract:

You’re sold on the benefits of structured content, but don’t know how to begin? This session shows you how to implement topic-based authoring by converting existing unstructured documentation into structured topics, even in regular office software such as Word.

The underlying process works for online help, user manuals, but also other content, such as wiki articles, training materials, etc., as long as you know which deliverables you need to create and their approximate purpose.

There are several stages to the process:

1. Identify topic type or types per content section, for example, concept, task, reference, or use case. Content which mixes topic types can be sorted out with a little care.
2. Re-chunk your sections to turn them into stand-alone topics. You can delete redundant or obsolete information which does not belong into a topic. Or you can spin it off into a topic of its own or integrate it with another, more suitable topic. Special strategies help you to deal with topics that are too complex.
3. Re-sequence your topics, so they flow nicely when users read not just one or two of them, but need to follow a complete process. If the topic sequence doesn’t flow nicely, you may need to add some auxiliary topics which orient readers and ensure a good flow.
4. Rewrite headings to guide readers to 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.
5. Add links between related topics to ensure that the structured topics work in various use cases, even if users refer only to few topics.

This presentation emphasizes practical tasks; you will

• How and why to create a content model
• How to identify topic types in existing content
• How to re-chunk content into true topics
• How to sequence your topics
• How and why to write good headings for your topics
• How to link related topics

We’ll meet on Monday, 19 May at 9:45 in 106 BC in the Phoenix Convention Center. Hope to see you there!

Second day at MadWorld 2014

A well-rounded program and excellent organisation at the second MadWorld user conference avoided many of the traps that can mar a sophomore effort and point to a way of growth into the future. The second day again saw great informative sessions and networking around doc issues and careers, not to mention lunch and drinks under the San Diego spring sun… 🙂

Advanced single sourcing of content in Flare uses a clever combination of snippets and conditions which are called, not surprisingly, “snippet conditions”. These allow you to maintain reusable chunks of content with slight variations – which one is ultimately displayed is controlled on the topic that contains the snippet.

In his single sourcing presentation, Paul Pehrson had many more tricks up his sleeve:

• To repeat a topic in the same TOC (with or without variation), put the topic content into a snippet and embed it into an empty unique topic container – else your breadcrumb trail in online help goes haywire, because it cannot know which of the two occurrences it should refer to.
• To reuse similar front matter across several PDFs, you can put the front cover, the copyright page, and the table of contents into a TOC of their own, import it as a nested TOC into each target and control the individual differences with variables.
• To maintain individual project styles and corporate styles, create your project CSS and import the corporate CSS into it by using the @import CSS command.
• To share condition sets or variable sets across two projects, store them as External Resources where you can keep them in sync with one another.

The lightning talk round was a very colorful fast-paced session. Passionate speakers addressed widely different topics, including

• A MadCap version of Jeopardy by Pam Coca (“Who is our tech comm game show host?” 🙂 )
• Several ways to avoid inline formatting with the help of Chuck Norris by Scott DeLoach
• MadCap’s latest group of spokespersons: Dentists who recommend Flare for more smiles than any other help authoring tool by yours truly

The 6 topics wouldn’t necessarily have warranted a full session each, but they were fun and valuable to have in a compressed 5-minute format.

Our addiction to meaning gave attendees food for thought as I led them through a quick overview of semiotics and mental models which included Japanese restaurants and misheard song lyrics. In the Q&A session we explored how we could apply such insights into cognition to offer users confidence in their tasks along with meaningful instructions.

Writing, editing and translating topics is frequently done by people who don’t have Flare and don’t need it either.

Mike Hamilton showed several scenarios to address special demands in authoring workflows:

• For writing and editing users of Contributor, you can customize exactly which Flare files, such as snippets, condition and variable sets, are available to them. You can also lock down certain text in Contributor templates to enforce structure and labels.
• For reviewers using Contributor, you can now apply conditions and variables when creating the review package, for example, to keep internal data out of packages for external reviewers.
• For translators of Flare topics, you can create customized export packages and choose to preserve the code of snippets and variables or to convert them into flat text.

For MadWorld 2015, my guess is that we might see fewer sessions on basic Flare techniques which are well-covered in available webinars and other information online. Instead, I’d recommend more sessions that show how MadCap supports tech comm workflows and business cases. These could cover, for example:

• How to integrate documentation and training content with Flare and Mimic
• How to build a business case around single-sourcing topics that can turn tech pubs into a profit center which leverages content as corporate assets
• How to use MadCap’s products in corporate, large-scale products, like Lynn Carrier has shown this year.

Overall, MadWorld was a very instructive, very fun event! The user conference format affords a welcome focus which sometimes gets lost in industry-wide conferences which have to try to satisfy more disparate needs.

CEO Anthony Olivier spoke of welcoming us all to the “MadCap family”. I think that metaphor is stretching it a bit. For me, it feels more like a versatile community of dedicated, often enthusiastic users who get to hang out with one another and with, say, a band we like – and we get to spend some time back stage in the hospitality suite. 🙂

First day at MadWorld 2014

The applicable advice about MadCap products from speakers and staff, the profound discussions about tech comm in general, and attendees’ enthusiasm to share and learn from another make MadWorld 2014 a perfect combination of a tool-centric user workshop and a “regular” tech comm conference.

The hip Hard Rock Hotel adds a flair of giddy excitement – after all, some of us 200 tech writers are a little too nerdy to feel comfortable when they’re treated like rock stars… 🙂

The welcome event started with a tongue-in-cheek video: MadCap’s signature cartoon figure Simon has become addicted to – the horror! – inline formatting. His brave MadCap colleagues stage an intervention to save him… I hope this video will soon come to a Youtube channel near you because it’s a lot of fun to watch!

Product Evangelist Jennifer White introduced many of the MadCap key players in attendance, then MadCap CEO Anthony Olivier welcomed us and encouraged us to join the “MadCap family” to learn and network.

To turbocharge our authoring, Nita Beck showed us how we could bypass some of the pretty, but slow-to-use Flare ribbon features for faster alternatives:

• Custom templates for topics and snippets can include  much of the recommended structure and formatting. Filling in such a template saves the time to manually reconstruct such structure and formatting in just about every template.
• Contributor can be used by tech communicators as a low-distraction alternative to Flare for initial drafts which keeps many of the more complicated features of Flare out of the way for the time being.
• Keyboard shortcuts for many Flare features are faster than doing the same with the mouse.

Pattern recognition elicited a lively Q&A session from the capacity crowd in my presentation. We found that, whatever patterns we recognize, they generally depend on their context in which the retain meaning. From there, we branched out to discuss information architecture and user experience design and how they also rely on patterns.  We also tried to tease out the pattern why my slides had broken the nice arrows and replaced them by the average sign in all places – but one!

Flare projects can support a scalable content architecture, as  Lynn Carrier showed. She described her employer’s project of introducing single-sourcing with Flare to cope with 3000 pages of docs per writer per year. The keys to her successful project were:

• Ownership to involve all writers and tap into each writer’s skills and interests to assure them they weren’t writing themselves out of a job.
• Infrastructure to make sure they have the tools and processes in place to create the deliverables in the structure and quality they customers need.
• Reuse to ensure the most efficient way to single-source content, they carefully mapped out where and when to use snippets, conditions and variables. Conditions are heavily applied on folders and topics move around in the folder structure so they are available for the products and versions where they are needed – and only there.  They use few variables because in-sentence, they create problems during translation.
• Publishing based on TOC templates and target templates ensures consistency in structure and easy maintenance.

Since we have very large projects as well, this was a very valuable session which gave us lots of ideas how to use Flare’s reuse and template features in a corporate environment. Lynn will have another presentation on the second day to show how a wizard enables customers to compile exactly the documentation they need into a PDF. This is something we’ve long thought of doing, so seeing her solution will be a great inspiration for us!

Face-to-face support beats written documentation any time which is why the “hospitality suite” is so great. It’s like walking into MadCap’s helpdesk as if the smartest MadCap users were your colleagues in the next room.

A good balance between sessions and networking opportunities allowed us to trade quirky, but powerful solutions around Flare that users have come up with, to trade career stories and make new friends among a group of technical communicators as diverse and friendly as you could hope to find at any tech comm conference.

Well done, MadCap, I’m psyched for day two!

Tech comm conferences too far, too costly?

European tech writers who don’t have the time or the money to attend a tech comm conference can still get a lot of knowledge and networking by attending the tekom Europe Roadshow – right in their backyard, comparatively speaking!

The tekom Europe Roadshow puts on one-day events which are easier to get to from many places around Europe and waaay cheaper than full conferences. They bring together professionals from the region for presentations, discussions and networking.

Find the roadshow event nearest to you:

• Paris, France: Monday, September 8
• Ghent, Belgium: Wednesday, September 10
• Eindhoven, Netherlands: Friday, September 12
• Copenhagen, Denmark: Tuesday, September 16
• Warsaw, Poland: Thursday, September 18
• Istanbul, Turkey: Monday, September 22
• Bucharest, Romania: Wednesday, September 24
• Vienna, Austria: Friday, September 26

This year’s topic is:

TechComm Workflow & Media Production
Integrate Intelligent Media Production in Your TechComm Workflow

But even if that is not your professional focus, it might still be worth going for the contacts.

For more information, visit the event web site.

(Full disclosure: I have spoken at an early precursor of the tekom roadshow and think it’s a brilliant format, but I’m not involved with this event series.)

Top 4 reasons that make MadWorld 2014 unique

Four unique reasons make MadWorld 2014 possibly the best tech comm conference you can attend this year. (Disclosure: I’m a happy MadCap Flare user and will speak at MadWorld 2014.)

MadCap’s second annual user conference takes place in the Hard Rock Hotel in San Diego, CA, on 13-15 April. It’s featuring not just MadCap’s technical authoring products, but tool-agnostic sessions on DITA, content strategy, professional development, and more. But I think you’ll get the most out of it if you are already using MadCap products or at least very close to doing so. If you are, here are my top 4 reasons that will make MadWorld uniquely useful.

1. Immediately applicable insights

Whether you are relatively new to MadCap or a veteran user, you can pick up helpful tips and relevant advice in sessions “Yeah, Flare Can Do That” and “Ride the Lightning (Talk)”. If you’re stumped for tactical or strategic decisions, you’ll find answers in “Going Solo: Best Practices for the Solo (Flare) Artist” and “We Built This City: Building a Scalable Architecture for a Flare Project”.

Because you know the tools and MadCap knows our tasks, MadWorld eliminates one of the most common complaints of professional conferences: Not quite relevant content. Instead, you can probably find an insight to apply back home in every session. No more “What happens in Vegas, stays in Vegas”! Plus, it’s San Diego.

2. Community networking and support

At MadWorld, you can plug in directly to MadCap’s dedicated and supportive community of users. Many of us folks who help each other on MadCap’s user forum or on LinkedIn will be there. Recently, regional user groups have sprung up in North America and even Europe as MadCap users realise the benefit of a more personal network.

You can hook up with other users to discover what they do with Flare and what ways they’ve found to tweak Flare. That includes the speakers who are regular users, too. Meet them over at MadCap’s blog where they share their expectations and their favorite three songs. I’m looking forward to meeting everyone and to share my experiences – and favorite songs!

3. Prime support included

MadWorld offers personal support from all the guys and gals we might otherwise just know from support emails. I’ve met MadCap staff at other conferences and found them incredibly helpful. They answered any question I threw at them. It felt like free, unlimited access to the proverbial soda fountain. MadWorld’s Hospitality Lounge by comparison is like an open door to the soda factory. I for one plan to bring a couple of crazy projects and indulge… 🙂

4. San Diego in the springtime

Yes, it’s been snowing and raining a lot and in unexpected places, too. But not in San Diego. Not for a looong time, as Jennifer from MadCap reminds us:

The last snow in SD was on 12/13/67! RT@ellispratt Something I thought I'd never ask:Will it be snowing in San Diego in April? #Madworld2014

— Jennifer White (@MsJennWhite) February 14, 2014

So I expect spring to be in full swing by the time we get there. Add to that the Hard Rock Hotel in the Gaslamp Quarter, the world-famous zoo and the beaches, and I start to sound like a tourist ad.

————————–

To sum up, I look forward to MadWorld, a conference with boot camp intensity and summer camp fun!

P.S. I will speak in the tool-agnostic track on cognitive foundations of tech comm:

• You’d Better Recognize! Pattern Recognition For Technical Communicators, on Mon, 14 April, 11:05 am
• Addicted to Meaning: Mental Models for Technical Communicators, on Tue, 15 April, 1:30 pm

And I’ll be on board for the round of lightning talks on Tuesday at 10:55.

Update, 10 March: techwhirl lists 5 Reasons to Attend MadWorld 2014, citing a total of 61 pieces of evidence!

Running lightning talks or Pecha Kucha

Lightning talks (or their siblings Pecha Kucha and Ignite talks) can be great fun. They’re basically presentation karaoke: You avoid death by PowerPoint – instead you get the occasional train wreck when the slides get away from the presenter. But usually, the giddiness of information overload in 5 to 7 minutes is very stimulating!

It just takes a little planning to make sure there’s room for the spontaneous energy to emerge. Here’s what makes lightning talks succeed, in my experience:

• Stick to the timeframe. For example, every speaker gets exactly 5 minutes to show exactly 20 slides where each slide is automated and timed for exactly 15 seconds. (Pecha Kucha uses 20 seconds each.) Now, this sounds a bit counter-intuitive to squeeze hi-energy lightning talkers into a tight format, but scrupulously sticking to it is essential to keep up the energy for the audience. Speakers don’t get to control the slides – which is the imminent danger and spice of every lightning talk! 🙂
• Figure in a bit of overhead time to explain the concept to the audience and to move from one speaker to the next. So for a 45-minute session, plan 6 talks or 7 at most.
• Have an MC facilitate the session. He or she explains the format, hands over between speakers and leads the crowd in applause, cheering, jeering, whatever seems appropriate.
• Curate the content, if necessary. Not every topic lends itself well to the restrictions of a lightning talk. Case studies and project stories of limited complexity usually work very well, as do Top 20 lists.
• Go for lightning flashes of insight, not totall recall. In my experience, the audience can expect to remember 2 or 3 talks of 7 – and maybe 4 or 5 points that really struck them.
• Lean on presenters. The one danger of a lightning talk buzzkill is speakers playing it too safe. Their slides look fine, but they only prepare one or two sentences per slide. They manage to deliver that sentence – and then wait 12 seconds for the slide to change. Sitting through that is quite lame for the last 15 slides… It’s difficult to avoid, but it’s more fun for everybody if speakers come with a tightly packed presentation – even if they stumble and then play catch up with the timer… Maybe encourage speakers to max out their topic and wring every last second from it, as if it was the last 5 minutes they ever had to share their enthusiasm.
• Select a good sequence of talks. This is also a bit difficult to plan, but in general it works best to have speakers with less energy and slides with less “wow” go first and then work up to higher levels of energy and “wow”.
• Demand the presos before hand. You need them to figure out the sequence and put them all on the same machine, so you can minimise the time between speakers. Some events publish the sequence before hand, others just announce it at the beginning of the session.
• It’s not a contest. At least I don’t recall any lightning talk round scoring or voting for a winner. Instead, the Olympic sprit rules: “The important thing is not to win, but to take part”. They are more like a show-and-tell in school or like a sing-song round in a bar: Many people take turns, but everybody who contributes is cheered on, if only for valiant efforts.

Top 10 tech comm conferences in 2014

Several worthwhile conferences that are relevant for tech comm are scheduled for next year. Here are eight I know about. Help me to round out the Top 10 by suggesting missing ones via the comments! Thanks to everybody who suggested more conferences via comments and twitter!

20-21 Feb 14, Bangalore, IN – tcworld India 2014

26-28 Feb 14, San Jose, CA – Intelligent Content

3-6 Mar 14, Palm Springs, CA – Writers UA West

10-11 Mar 14, Budapest, HU – Write the Docs

13-15 Apr 14, San Diego, CA – MadWorld
I will present sessions on pattern recognition and mental models and a lightning talk.

05-06 May 14, Portland, OR – Write the Docs

18-21 May 14, Phoenix, AZ – STC Summit
I will show how to get From Unstructured Documentation to Structured Topics.

5-6 Jun 14, Kraków, PL – UA Europe

18-20 Jun 14, Gatwick, UK – Congility 2014

Summer? Cincinnati, OH – Open Help (no details for 2014 yet)

16-18 Sep 14, venue unknown, UK – TCUK (web site not yet available)

13–15 Oct 14, Portland, OR – Lavacon (web site not yet available)

11-13 Nov 14, Stuttgart, DE – tekom/tcworld (web site not yet available)