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

Advertisement

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!

Why a content spec saves you time and money

A content specification will save you troubles, time, and money, especially when you’re not the lone writer on a documentation project. It will ensure that you offer your users consistent and holistic documentation across a team of writers.

A content specification is a list of all topics to be created which ideally maps planned topics to requirements and/or designs to ensure comprehensive and complete documentation. It usually comes in a table with one row per topic, listing:

• Topic heading and/or file name
• Topic type (concept, task, reference, or whatever else you may use)
• Topic owner
• Writer (in case writers may be different from topic owners)
• Reviewers (for example, subject-matter experts)
• Date ready for review or for post-review editing (depending on your workflow)
• Mapped deliverables (where the topic appears, for example, a certain user manual, the online help, etc.)
• Time estimate (how long will it take to write the topic, optionally, including review)
• Documentation task type, to help you estimate time:
  • Create new topic
  • Major rewrite of existing topic
  • Minor fix or addition to existing topic

Without it, you risk delivering a bunch of topics with gaps in some places and overlaps in others. You can still string them together, but no overview topic can convey a coherent content experience, if you didn’t plan for it and bake it into the topics and their structure.

So a content spec is a blueprint of your documentation project, just as you would create one before you start building a house – or design any kind of experience.

Yet content specs often elicit negative reactions…

“Oh, but we’ve managed without one so far…”

Many tech writers I know are very competent, and a few are lucky to boot. Considering all their projects with more than, say, 50 topics which didn’t use a content spec, I’d bet half of them are incoherent (“organically grown” is an oft-used euphemism).

The cost doesn’t stop at poor user experience. Such examples are also more difficult and more expensive to maintain, especially if you have overlapping topics and don’t remember to update both of them…

“Bah, reality eats specs for lunch…”

To an extent, yes. But on the whole, reality is an orderly patron. In my experience, the final documentation reflect the approved content spec in up to 80% of the topics. An average 10% of the topics get added during the writing, where concepts or prerequisite and auxiliary procedures are found missing. Another 10% of the topics get reorganized because the initial content spec misunderstood something, or because content simply makes more sense somewhere else.

“Even if, we’ll fix it later…”

Yes, you can. But once again it’s very expensive. Remember that the list of topics is only one result of the content spec. Their structure is another. Finding that a structure by workflows is inferior to a structure by, say, instrument, requires not just re-ordering topics, but re-writing a lot of them.

You can avoid this by drawing up a complete content spec before you write a single topic and getting it signed off by the key stakeholders, so they know rather well what documentation they will get. The 20% deviations mentioned above are usually justifiable, if they conceivably improve the deliverables.

– Given that content specs are a big help in creating and maintaining efficient and effective user documentation, I strongly recommend using them. If you have any experience with or without content specs, I’d love to hear it.

Paul Perrotta on change management at tekom/tcworld

Content management/strategy and the business of tech comm were my two focus areas during the tekom/tcworld conference in Wiesbaden, Germany, last week, and I will summarise some of the sessions I attended in several blog posts.

(For a general overview of what tekom is like, refer back to How German is tekom and tcworld? UK tech comm consultant Ellis Pratt and I have been commissioned to sum up this year’s event for an upcoming issue of ISTC’s Communicator magazine.)

Paul Perrotta on change management

Paul Perrotta from Juniper Networks offered two sessions on change management in tech comm. He reported on his unit’s journey from siloed, bickering, intransparent groups to a more efficient Information Experience (iX) organization.

Part of the problem is that we in tech comm are often pretty bad at saying what we do and what value we provide to the company and to customers. Instead, “docs happen” frequently in a black box. If you measure how well-regarded each unit is by their budget increases, a black box is not a good place to be in, because it won’t get you better funding. Executives don’t know (and don’t need to know) how tech comm works. But they need to know whether it’s successful and how it helps them be successful. And whether 8 dollars spent on it will increase their bottom line by 10.

So make tech comm more business-like and make managers’ worries your own: How can we increase customer satisfaction? How can we contribute to increase market share? Address these challenges to show the value tech comm contributes and how you can help the business to deflect some of the threats, such as:

• Doing more (work) with less (resources).
• Deferring costs to a less certain future.
• Offshoring tech comm.

Here’s what you can do specifically:

• Define a vision and mission for tech comm to clarify what they do – and what they don’t do. (See also “Why you need a tech comm mission statement“.)
• Make improvements manageable by chunking them up into strategic initiatives.
• Dissolve the documentation siloes by architecting and governing all content as a whole.
• Improve content to make it complete, searchable and findable.
• Connecting tech comm with marketing, sales and support to contribute to and benefit from the same content.
• Rebrand tech comm as information experience to emphasize its contribution to the customers’ experience.
• Focus on users and engage with them, for example, via user satisfaction surveys, feedback, social media.
• Install an iX customer advisory board which meets regularly.
• Seek out managers with the power and money to help you and map out your allies throughout the organization.
• Make tech comm measurable and operationally efficient:
  • Link tech comm to development metrics where possible.
  • With proven competence, you can aim for 5% of R&D spend which is industry best practice in IT.
  • Ask how much of the product price tags the documentation is worth.
  • Show what (else) you could do with X more money.

Some of the results that Paul found:

• Many customers are happy to offer feedback if they find they get heard, and tech comm improves as a result.
• An ongoing discussion with users builds trust and customer loyalty.
• Commonly governed content becomes more reliable and more easily findable for employees and customers alike.
• Managers will support you because your success is their success of you demonstrate competence and that it’s easy for them to help you.
• If you map your projects to executives’ objectives, you can clarify what you can and cannot do with available resources.
• Achievements require focus to reap their full benefits – and then advertisements to make sure executives realize that you can work like a business…
• To measure their achievements, tech comm quality metrics are not enough; you need customer engagement/experience metrics as well.
• As a side effect, you will have to abandon an implicit ethos that treats tech comm as special, as an art that creates books.

1st day of sessions at TCUK 13

On its first day of sessions, TCUK13 offered very diverse sessions. My selection of presentations – and hallway conversations – focused on cognitive science, the future of tech comm, the business side of our industry as well as managing tech comm, this year’s specialist stream.

Sarah O’Keefe on “Fame, glory and… tech comm”

Sarah’s opening keynote urged us to unleash our inner pirate and “go for the booty” of corporate resources and attention – in other words: to follow the money. We tech comm’ers need to understand the objectives and KPIs of C-level executives, develop a content strategy that supports these objectives and then profit (before marketing or other departments do, as Ellis Pratt later pointed out in his rant).

This way we can create effective tech comm which meets both business needs and user needs – as opposed to artisanal tech comm which fails business goals or cheap and merely adequate tech comm which fails users.

My session on semiotics and mental models

My own presentation Addicted to meaning: Mental models for technical communicators was attended by approximately 50 people and quite well received, I thought.

It’s essentially a brisk walk through a couple of cognitive concepts that underlie much of tech comm. After considering what meaning actually is and why we technical communicators should even care, I looked to semiotics to explain how meaning works in communication – and why it still sometimes fails in tech comm. The second concept is mental models which can explain how and why we create meaning – and how we can create meaningful documentation.

Adrian Morse on “The challenges of remote management”

Adrian drew on his experience of both working at home and managing technical communicators who work at home to explain many of the challenges of managing writers remotely. His tips applied to most teleworking scenarios, from occasional home office days to full-time teleworking by some or all of the team members.

Remote working and managing requires thought-through policies and a good reliable setup that starts with the appropriate hardware and network services and extends all the way to regulating PC administration, backup policies, etc. and complying with corresponding laws and EU regulations.

Adrian emphasized how important communication is as long as someone, anyone teleworks: You need to agree on mutual expectations in terms of hard objectives and performance, but also in terms of softer factors of answer times and availability for mail and phone contact. Just as working face-to-face, teleworking requires regular meetings, both 1-on-1 and of the team as a whole. Also make sure you have good ideas and policies for when and how you allow people to enter teleworking scenarios and when and how they will end them again!

Ray Gallon on “The Quantum Funnel”

Ray’s talk dovetailed with my own: His reference to creating scripts which explain how we behave in a restaurant was very close to my own example of how mental models determine our approaches to and perceived options in restaurants.

His premise is that today’s practice of learning is much more scattered and autonomous than it has previously been when learning was more controlled and directed. Such learning leaves more and more crucial gaps than before. To make sure that people (and users of tech comm specifically) can successfully fill their knowledge gaps, learning becomes more important than knowing.

One such approach is “connectivism” which understands learning as the process to search and connect concepts, ideas and fields. In this context, learning must not only answer the questions “what?”, “how?”, “where?” and “when?”, but also “how to be?” and “how to be with others?”. People in general and tech comm audiences in particular, increasingly learn in self-directed and creative ways by social collaboration, together with others. The role of teachers shifts to facilitator, that of technical communicator to curator.

This will emphasize both social and cognitive skills in the future, when we learn by moving through these stages:

1. Exploring and understanding
2. Representing
3. Planning and executing
4. Monitoring and reflecting

Applied to tech comm, this means our model shifts from a gatekeeper of knowledge to that of a curator and storyteller, as we avail ourselves of different types of contextual information, some of which our outside of our control:

1. Internal documentation, such as progressive disclosure.
2. External information, such as it is in Wikipedia.
3. Interactive information, such as MOOCs and commenting functions support them.

– Feel free to leave comments about any of the sessions, whether you have attended them or not. I will try to answer them as well as I can.

“Bake your taxonomy” workshop at #tcuk13

Knowing your audience, their needs and use cases is key, not only when writing documentation, but also when designing its topic structure, navigation structure and taxonomies. That’s the insight  around 50 participants came to at the end of the “Bake your taxonomy” workshop which Chris Atherton and I facilitated at the first day of TCUK13 in Bristol.

The insight itself is not revolutionary, of course, but it gave attendees a chance to try out content modelling and card sorting first-hand and consider alternative designs and difficult decisions that go into structuring documentation just right.

Explaining taxonomies and content models

Chris and I started the 3-hour workshop with a 30-minute presentation:

Organically grown content often develops into a mess of good, bad and ugly content with little or no discernible structure. An information architecture that was designed by central oversight and with a guiding higher principle might resemble a cathedral – but the organically grown reality more often resembles a bazaar.

Both models have their drawbacks: The cathedral might be out of touch with what users need to do and know in their daily lives. The bazaar supplies that better – but it’s much harder to navigate, unless you know it really well.

Chris and I presenting (photo by @JK1440)

Enter taxonomies, which are hierarchical classification systems. Just as children and veterinarians use different systems to distinguish and classify animals, so users and we who write for them can distinguish different topic types and structures and different ways to navigate topics according to their needs and use cases.

Exercises: “Bring out the scissors!”

Then we formed 12 groups of approx. 4 and set off on a couple of exercises:

• Content modelling. Take a documentation set (in our example a user manual for a handheld audio recorder) and develop topic types and content models for users, their needs and use cases. Then re-chunk the manual into new topics according to topics types and users.
• Card sorting. Take the topics and find the best sequence and hierarchy for them.  Also consider the documentation format such as print, online, etc., and topic re-use opportunities between different formats and use cases.

Workshoppers baking their own taxonomy (photo by @JK1440)

After the first exercise, we had a short roundup of the different approaches and results of the groups and a short break, before we embarked on the second exercise.

As it turns out, it’s really difficult to separate between content modelling (structuring within topics) and card sorting (structuring of topics). And in many cases there might be few benefits to separate those tasks. However, if you do the content model first and in isolation, you might have a more stable content model that lends itself to more than the structure you’ve used to pour it into.

To sum up, it was a very lively workshop with many good discussions – mostly within the groups of four, but also in the roundups when we collected approaches and insights. Chris and I thoroughly enjoyed it and learned a lot about what a diverse bunch not only tech comm audiences, but also we as practitioners can be.

If you’ve attended the sessions or want if to know more about what happened and how, feel free to leave a comment.

Snack-size tech comm videos from STC13

Scott Abel talked several tech comm speakers, bloggers and other luminaries into short videos at this spring’s STC Summit in Atlanta. The results are now available as Adobe Thought Leader Interviews at STC SUMMIT 2013. Most videos pack an interesting, usually well-argued insight into a minute or two. Taken together, they’re a good survey of topics and trends that were bounced around the Summit – and a perfect excuse to relive some of the #STC13 spirit!

Here are some of my favorites and what I like about them.

Sarah O’Keefe: Tech Communicators Need to Focus on the Business explains why tech comm’ers need to see how their content and their deliverables fit into the larger business schemes of their organization or client. It’s not exactly the first time Sarah has put out this message, but I consider this a recurring theme and one of the most urgent challenges for our profession.

Ann Rockley: The Benefits of Content Modeling shows how and why single-sourcing and content reuse requires prior planning. You need to model your content to ensure it comes out useful in the different formats. I appreciate Ann’s message that you not only need to do it, but you need to do it right.

Bernard Aschwanden: Benefits of Structured Authoring offers a primer on DITA and neatly sums up why the separation into concept, task and reference topics makes sense in a lot of cases. I like the video because it’s quite a feat to summarise both DITA and topic-based authoring in 2:40 minutes – and with examples to boot!

Rahel Bailie: Reclaiming Content Strategy urges tech comm’ers to reclaim the content strategy turf from the marketing people who may sell themselves better and know about writing copy, too – but we tech comm’ers can add the badly needed technicial knowledge as well. I cherish Rahel’s vote of confidence that we can and should reach out into this neighboring discipline!

Andrea Ames: It’s Not Your Mother’s Tech Comm Anymore argues that tech comm has to change and is in fact changing as users consume it in ever-developing context which makes tech comm’ers, and in fact users, too, the curators of documentation. I enjoy Andrea’s enthusiasm that blends “must do” and “can do” in most of what she does.

Oh, yeah, and then there’s my own 1:17 minutes of fame, ranting about tech comm’ers who wait for instructions and tasks. My point is basically: “Don’t Ask for a Mandate“, but rather prototype what content needs you find and let the solution sell itself. (I stand by my argument, though I don’t like my overzealous look of a young lawyer fearing to screw up his first court case… 🙂 )

But I highly recommend checking out the entire series of interviews, because they cover a wide variety of topics, technologies and tools!

STC13: Alyson Riley about effective IA

In her session “Building Effective IA Teams in Resource-Challenged Times”, Alyson Riley from IBM offered her take on the recent theme that tech comm needs to “speak business” to prove its worth. (This is part of my coverage of the STC Summit 2013 in Atlanta.)

Alyson argued that “nice to have” initiatives are no longer compelling enough to get tech comm a budget or a mandate. To play a mission-critical role in a corporation, tech comm must plug into the corporate strategy. However, that strategy and its stakeholders usually isn’t waiting for us to put in our two cents. So we tech comm’ers must:

1. Focus on corporate strategy as opposed to tactics.
2. Play to the motivations behind the strategy, so we can come up with ways to support it with our unique skills and contributions.

The following moves can help with that second step:

• Address the “buyer evaluates” and “buy” stages of the product. Usually, we speak to the “customer uses” stage of our product where there’s often more cost than income. The challenge is to make it compelling for buyers and sales to also use our content to their benefit in the more profitable stages. A good start is to ask sales: “What is the hardest part of your job?” and see if we can help them with the information we provide.
• Influence social content to help leads along the marketing funnel from awareness to loyalty and advocacy. That doesn’t mean to “sell out” completely to marketing. It’s often as easy and sensible as including customer benefits in our content. Simply add the “why” to the “how” and give clients a chance to understand and promote your product.

Both moves boil down to the same principle: Don’t educate stakeholders in sales, marketing, product management, etc. about the product. Instead, imagine what the success of these respective stakeholders looks like and address that:

1. Analyze opportunities your product can address in the terms of sales and marketing.
2. Craft an effective story that centers on your content and how it can drive revenue, sales, customer satisfaction and loyalty.
3. Prove it with metrics that speak to the stakeholders.

When it comes to metrics, page views of documentation usually don’t impress managers much. Instead, Alyson suggested “time-to-value” (TTV) which measures the customer’s time from buying or paying for the product to the moment they reap value from it. This is similar to “return-on-investment”, but TTV can be clearer to measure when investment consists of one-time payments plus maintenance fees. Also, it’s easier for tech comm to favorably influence TTV… 🙂

First day at tekom12

This is my second year at tekom, the world’s largest tech comm conference held annually in Wiesbaden, Germany. tekom is nominally a German conference that coincides with its international sibling conference tcworld in English. As the hashtag confusion on twitter shows once again, the English tech comm scene tends to use both names. (Which makes me wonder why the organizers don’t simply use the tekom name for the whole thing which has sessions in English and German…?)

My session on meaning in tech comm

I skipped the morning sessions, since I was feeling a little under the weather. I didn’t even get to tekom until around 1 pm, but in plenty of time for my own presentation on How our addiction to meaning benefits tech comm. I had submitted two very different talks, and I thank the organizers that they picked the “wacky” one. And to my surprise, I had about 100 people interested in meaning, semiotics and mental models! I thought the talk went well. I had some nice comments at the end and some very positive feedback on twitter afterwards.

You can find my slides on Slideshare and on the conference site. Sarah Maddox has an extensive play-by-play write-up of how my session went on her blog.

Content Strategy sessions

Scott Abel has put together a very good stream of content strategy sessions, where I attended the presentations of Val Swisher and Sarah O’Keefe (I also blogged about Sarah’s presentation). I’m not sure if my observation is accurate, but it seemed to me that there was less interest and excitement about this stream this year than at the premiere last year. As befits content strategy, both sessions I attended were strategic, rather than operational, so they dealt primarily with how tech comm fits into the larger corporate strategy.

Marijana Prusina on localizing in DITA

Then I went to hear Marijana Prusina give a tutorial on localizing in DITA. I have no first-hand experience with DITA, but I use a DITA-based information model at work, so this gave me a reality check of what I was missing by not using the real thing. Seeing all the XSLT you get to haggle with in the DITA Open Toolkit, I cannot exactly say that I regret not using DITA.

Beer & pretzels

Huge thanks to Atlassian and k15t who sponsored a reception with free beer & pretzels – and even t-shirts if you left them your business card. This coincided with the tweet-up. It was good to see tech comm colleagues from around the world (Canada, the US, Australia, France and Germany, of course). Some I had known via twitter or their blogs for a while, so it was a welcome chance to finally meet them in person.

– For more, many more session write-ups check out Sarah Maddox’ blog!

– So much for the first day, two more to come. I’m looking forward to them!

Turning tech comm into a biz asset by Sarah O’Keefe

Turning technical communications into a business asset, according to Sarah O’Keefe, is mainly about justifying cost; it is necessary, but possible. Her session at tekom12 was part of the Content Strategy stream, presented as last year by Scott Abel.

How expensive is your documentation – really?

Much progress in a tech comm department gets stumped when we, the tech writers, say: “Ah, that’d be great – but they’ll never pay for it!” What that really means is: “‘They’ don’t see the value (or the urgency).” So to prove the value behind tech comm, we need to justify how we can either save money (by reducing effort) or how we can generate additional revenue (by producing value that exceeds our cost).

Sarah points out several way to do this:

• Show how tech comm can address legal or regulatory issues. Avoiding lawsuits is a great way to save your employer’s money!
• Control the real cost of tech comm, because “cheap can be very expensive”: Yes, you may get something akin to documentation from a secretary or an intern, but…
  • Is your documentation efficient to maintain?
  • Does it scale or allow publication in other formats?
  • Does it actually satisfy your customers and support your brand – or does it stab your corporate value statement in the back?

Cost containment strategies

Sarah mentioned several strategies to control documentation cost.

The first bunch has to do with efficient content development:

• Reuse as much content as possible: Write once, use many times, either in different places of the same format or in different output formats.
• Automate formatting: Manually handcrafted formatting of deliverables can be a huge cost factor. It’s not uncommon for tech writers to spend 20% of their time (and hence a sizable chunk of money) on formatting output. Automate this, by relegating format either to templates or CSS.
• Localization scales content efficiencies: Localizing or translating your content will be all the more inefficient, the more inefficiencies you have in your original documentation processes. This applies to content reuse, inefficient content variants and formatting.

Then there’s cost reduction outside of the tech comm team, for example, in tech support:

• Consider whether your documentation is good enough to deflect the maximum possible number of support calls. Anything that users cannot find in the documentation, whether it’s missing or unfindable, drives up costs for your tech support staff.
• Ensure your tech support staff has access to your documentation in formats they can work with efficiently. Downloading and then opening a document of 10 or 20 MB, is not only clumsy in its own right, it’s also likely that it doesn’t present the required information in the most efficient way…
• Ensure your documentation content is actually useful to tech support staff: It must not only be accurate, but also up-to-date. Consider the nightmare in terms of costs and maintenance if tech support spun off their own documentation to augment the “official documentation”. Instead, invite them to contribute to the documentation you create.

Make documentation more strategic

Then there are a few strategies to make documentation more strategic, or rather, more strategically valuable:

• Ensure your documentation is not only searchable (so it’s captured by publicly accessible search engines), but also findable (so people know where and how to get to it) and discoverable (so people link to it, from blogs or forums or twitter or the like).
• Align tech comm to larger business goals: Find a corporate goal, preferable one that is tied to revenue to be made or cost to be avoided and show: If the tech comm team did this, it could contribute approximately that much money (in savings or additional revenue) to that larger corporate goal.

Conclusion

Sarah’s talk was geared towards the strategic angle of tech comm, but succeeded in making valuable points very clearly. Whether you can actually apply her advice in your situation may depend on how much managers with budget control feel the pain of improving tech comm.