Strategic Technical Communicator panel at tekom12

Marijana Prusina, Nicky Bleiel, Sarah O’Keefe and Dr. Tony Self pooled their experience in an interesting and versatile panel session about the more strategic aspects of our profession.

The Strategic Tech Comm panel (photo thanks to Axel Regnet)

It was not so much a discussion as a fast-paced session of the experts sharing their thoughts on strategic issues and problems, so I’ll simply list some of the insights:

• Domain knowledge for a certain industry (as opposed to general tech comm skills) can be a great asset that you can use to build a career on, but it’s not necessary to become an expert in any one domain.
• To get a mandate or money from management, don’t argue in terms of quality, but rather in terms of cost: Show how improving documentation will either reduce cost or create additional revenue.
• Freelancing can work well, but you will need some things which are less essential if you are employed:
  • Considerable project management skills – even if only for your own projects
  • A good network of satisfied customers, other people who know and like your work, and other freelancers with whom you can exchange tips and tricks – and maybe even projects if they’re better skilled to take them on or when you are busy.
  • A snappy definition of your core services, skills and profile.
• To improve the reputation of tech comm and exert influence in your company, try these strategies:
  • Volunteer, if you can afford to, whether in a professional tech comm association or a standards committee.
  • Underpromise and overdeliver on your deliverables – and meet the deadlines you agree to.
  • Write a book – but be aware that you’ll mainly do it for marketing and influence: It’s a lot of work, and it won’t make you rich.
  • Be the advocate of users, who are satisfied, more productive and less costly to your tech support thanks to good documentation.
• Take all the training that makes sense to you and that you can get. Don’t forget about domain skills and software-related skills, for example, for API documentation. When training, keep in mind your resumé and what value you will add to your customers or your employer by adding a certain skill.

Advertisement

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.

TCUK12, day 1: Workshops & company

The first day of the ISTC conference TCUK12 offered workshops and great opportunities to meet tech comm’ers from all walks of life and many corners of the earth.

When I arrived late on Monday evening, I promptly headed for the bar and joined the advance party for a last round – which lasted so late that I’m not even sure in which timezone it was 2 am before I turned in…

Robert Hempsall: Information Design 101

Robert Hempsall offered a great and engaging hands-on Information Design 101 workshop about information design. The workshop focused on the five key areas of content and structure, language, layout, typography, and lines and spatial organization. Using a formal application to vote in English elections by mail, Robert led us through the process of designing the form to maximize clarity and usability.

Thanks to our versatile and engaged group of delegates, our work on the form was not only lively, but showed how different disciplines contribute to the solution of better information design, from tech comm (with its principles of minimalism and parallelism) via user interface design (with its emphasis on making completion of the form as easy and painless as possible) to graphic design.

In this sense, the workshop presented a good example of “design by committee” (which is usually a terrible idea): We discussed the most intuitive and user-friendly sequence of the form’s elements and how best to phrase the section headings, as questions or as imperatives. A seemingly innocuous “all of the above”  check box also caused a debate: Should it precede the individual options, to make completing the form quick, easy and painless? Should it come last, so users hopefully first read and reflect on the options? Or should it be omitted altogether, so users have to think about each option and select all that apply.

Form design is maybe not among the core tasks for many tech writers. Yet I’ve found several challenges in it that are strikingly similar to getting a topic structure just right, whether it’s a consistent, indicative heading, good, clear instructions or logical structure.

Rowan Shaw: Quality Across Borders

Rowan Shaw‘s workshop Quality Across Borders: Practical Measures to Ensure Best-Value Documentation in Global Technology Businesses focused on creating documentation both with authors and for users who have English as a second language (ESL).

As in introduction, Rowan presented us with 10 sentences each of which had some element that can create a problem for ESL readers, ranging from “10/03/12”, which could mean 3 October or March 10, to metaphors and slang.

If you need to hire ESL authors, it can be helpful to ask applicants to sit for an exam which tests skills such as procedure writing, fluency of expression, structuring, detail, consistency – but also their motivation for applying, to spot those candidates who want a foot in the door, but might not be interested in tech comm in the long term. We discussed a sample test, whether it was applicable and appropriate in all cultures.

Rowan suggested that, given the practicalities of global ESL authors, you might have to settle for less than perfect profiles in candidates. Then it is important to know which skills are easier to teach someone on the job, for example, grammar, structuring, capitalization, punctuation and how to use a style guide. Other skills are harder to teach, such as an eye for detail, audience orientation, logical thinking, but also more intricate language skills, such as prepositions and correct modifiers.

Again, this workshop benefitted tremendously from the diverse talents in the room and the experiences delegates brought to the topic.

The right company

I keep harping on how much I enjoy and benefit from meeting other tech comm’ers. Just on the first day:

• I found that several other doc managers are also wary to hire subject matter experts, who are less committed to tech comm, because they might just want a foot in the door (see above).
• I had an immensely helpful conversation with someone who’s a visiting professor and who could give me tips and ideas that I can try as I consider teaching as a future path.

So day 1 was very fruitful already, and I’m looking forward to more sessions and conversations to come.

Leah Guren’s Tales of Terror: Avoiding Project Disasters at STC12

Leah Guren presented a spunky, fast-paced session of project train wrecks that offered many lessons to managers and writers in tech comm projects. She presented disasters in five categories: Communication, people, politics, implementation and global issues.

“Failure to communicate”

When poor communication derails tech comm projects, it’s often due to missing information. Specifically, a project may have failed to ask the right questions (almost like performing due diligence) or failed to insist on getting the questions answered by the subject-matter experts or the specifications.

To prevent this problem, don’t write blind! Ensure that the project is clear not only on the product, but also on the users, their scenarios and workflows. This is a tricky issue that it afflicts even experienced tech comm’ers who may be tempted to wing it. But a checklist can help you to cover all your bases.

Of monster managers and quirky SMEs

People can jeopardize documentation projects, especially if they bring together people who don’t work together in projects very often. As a tech communicator, you might deal with an annoying monster manager breathing down your neck one minute and placate a quirky subject-matter expert the next.

Leah’s advice was straight and matter-of-fact: You can’t fix crazy, so don’t take it personally. You might even find yourself documenting irrational processes and workflows.

Of stakes and turf wars

Politics can endanger projects when agendas clash and turf wars arise between fiefdoms. This is actually the reason why so many organizations still run a balkanized business where development proceeds in distributed siloes. The resulting documentation often perfumes the pig though it can hardly help being inconsistent or disparate.

Consider carefully whether it’s worth the extra effort to try and clean up broken workflows and GUIs after the fact – or if you even have the leverage and the clout to be successful.

Of implementation constraints

Implementation can throw a wrench into a well-planned project, when you find you lack skills, resources or access to such. Sometimes you’ll see warning signs, such as “scope creep” when a project quickly becomes more complex than you thought originally. For example, Leah talked about a project which was to cover a complete product overhaul – and an SAP integration on top of it.

This is a case for a senior stakeholder or manager who needs to assess the situation and who can hopefully reschedule tasks or reassign resources.

Of intercultural complexity

A recent, often unexpected problem in tech comm is complexity due to globalization. Global business often doesn’t scale seamlessly, and tech comm (as all culturally contingent practices) even less so.

If your project involves countries, markets and languages you haven’t been involved with yet, take extra care. However, as companies find out again and again, there seems to be no fool-proof way to address this issue, other than trying to look at similar case studies.

Solutions and remedies

Leah held off suggested solutions until the end. The good news is that many projects can address many of the issues to an extent with standard project management tools and best practices.

• Use a project check list that defines scope, deadlines and involved participants, incl. their roles, goals and expectations. Include also SMEs and other stakeholders.
• Track project status meticulously and insist on regular reporting – from participants and to the steering committee.
• Have a contingency plan, if at all possible, which can buy you extra time or replacements for people if you need them.

Salvaging wrecks

But the best-laid plans don’t always guarantee success, so you might find yourself with a project train wreck that needs salvaging. Leah’s advice, at least to me, wasn’t revolutionary or new, but rather an encouragement to stay honest:

• Don’t hide from problems or difficult people. They won’t get better and they won’t disappear by themselves. Face them and address them as soon as possible. If nothing else, you’ll sleep better.
• Cut your losses, if you have to and find the right time to cut your losses, before you throw good money after bad. If you, be clear to everyone (including yourself) what went wrong and why.

The assurance of coaching

After her presentation (which already included several case studies that I have omitted above), Leah solicited further case studies and problems from the audience. This rounded out the session quite well which felt like coaching on speed.

For me, the most important take-away was that projects can and will go wrong for all kinds of reasons that are beyond our control. But if we are alert and honest to ourselves, we can salvage most of them, wrap them up with decent success and saved face.

Summing up Scriptorium’s tech comm experts webcast

In Scriptorium’s “Ask the experts” webcast on 17 April 2012, Sarah O’Keefe, Nicky Bleiel and Tony Self reflected on frequently asked questions and trends. Here’s a timed play-by-play synopsis, so you can access the bits in the recording that interest you.

I try to provide teasers, not spoilers, so scoot right over to Scriptorium’s blog and check out the meaty answers for yourself!

FAQs

The panel starts with the questions they hear most often, from the underlying architecture via the tools to the deliverables.

5:46 – What is the best help/XML/CMS tool to use?

Tony tackles this first question. While there is no clear, short answer, Tony sums up some criteria which can guide your choice to selecting a system that works for you.

9:20 & 14:20 – What should we be delivering?

Nicky hears this one frequently – and often the underlying sentiment is: “So many outputs, so little time.” Again, there’s no simple answer that suits everyone, but Nicky outlines how to make an appropriate decision. And once you throw single sourcing in the mix, you’ve likely got a scenario that works for you. (They go back to this question after the next one, that’s why there are two timestamps!)

11:54 – Should we implement DITA/XML?

Sarah has several answers for this question: Showing an ROI is tricky, but most compelling – and it is more likely in some scenarios than others. The strategic aspect of making your content future-proof helps, but it may not be sufficient for your business case.

Hot topics

Next up are some more or less controversial questions:

18:50 – Should we use a wiki for documentation?

The experts chime in with several perspectives that can help you make a decision. Tony thinks it can be a valid format for many use cases, Sarah cautions of the very different processes a wiki brings.

25:10 – Content strategy: Is it a fad or fab?

The experts’ answers focus on what content strategy actually means for technical communications, from “we’ve basically been doing it for years” to embracing it as part of our profession’s maturing process to new job roles and titles.

30:30 – The tech comm career: Is it awful or awesome?

This one is interesting: The experts see both, the glass half empty AND half full. The consensus is that the role for technical communicators is changing, and fast, so there are challenges and opportunities to those who adopt.

Audience participation time

For the last round, the webinar audience submits some questions for scrutiny:

37:50 – Can tech comm be complex when products get ever simpler?

The panel is not ready to dumb down documentation at all costs. Complexity may be warranted depending on the products and audience expectations.

42:15 – Is agile good or bad for tech comm?

Agile can be good for tech comm, when it’s implemented well. Tony also points out that agile may give technical communicators a stronger role in the development process.

45:55 – Can product specs be turned into docs with a single edit?

It’s hard to tell without knowing the details. But probably not.

How to disrupt techcomm in your organization?

If you need to “disrupt” your tech comm content, I believe it’s more beneficial to integrate content across the organization than just to get tech comm to become more business-oriented or more like marketing.

The idea comes out of a worthy new collaborative project Sarah O’Keefe launched last week, Content Strategy 101: Transform Technical Content into a Business Asset. (This blog post is based on a couple of comments I’ve left on the site.)

Tech comm goes to business school

A recurring discussion is that tech comm needs to be more business-like to be justifiable in the future, not only on this blog but also elsewhere. Proponents of this view definitely have a point, if only because tech comm is often seen as a cost center and finds it hard to claim a return on investment.

I think, however, that this view is detrimental to all involved parties:

• Tech comm risks to abandon its benefits to users and quality standards in an attempt to be “more like marketing”.
• Managers may risk permanent damage to the documentation of their product without solving the bigger problem.

Breaking down all silos

The bigger problem often is that most content production is inefficient – because it occurs in parallel silos. Many companies have gotten good at making their core business more efficient. But they often neglect secondary production of content which remains inefficient and fragmented.

I’ve seen several companies where marketing, technical communications and training (to name just three areas) waste time and money. Due to inefficient, silo’ed processes, tools and objectives, they create similar, overlapping content:

• Marketing and tech comm create and maintain separate content to explain the benefits of a product.
• Tech comm and training write separate instruction procedures for manuals and training materials.

Once companies wake up to these redundancies, all content-producing units will face pressure to streamline content and make it easier to produce and reuse. This will revolutionize corporate content production and publishing.

Quo vadis, technical communicators?

I think this issue raises two questions for technical communicators.

The strategic question is:

Which kind of content disruption is more beneficial for the organisation and for customers: Folding tech comm into marketing or integrating all content with a corporate content strategy?

The answer depends on several issues, among them:

• Does your content serve the product, the company or the customer?
• Is there a business case for a corporate content strategy?

The tactical question is:

What’s the role of technical communicators in this content disruption: Are they the movers or the movees? Are they shaping the strategy or following suit?

The answer again depends on several issues:

• What is your personality, clout and position in the organization?
• Which team has the most mature content and processes to be a candidate to lead any kind of strategic change in content?

I think tech comm can lead a content strategy, especially if and when the tech comm team knows more about content than marketing or training or other content producers.

My webinar slides as PDF handout

If you’ve attended my webinar “Getting ahead as a lone writer”, you might be interested in the slides in PDF:

They were supposed to be made available to attendees by the STC, but apparently that hasn’t happened as I’ve just learned yesterday.

If you have any more questions about the webinar or being a lone writer, feel free to browse my previous posts or pose your questions in a comment below.

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.

Short-sighted seduction: Tech comm as a task

Treating tech comm as a task, not a profession, is seductive, but harmful.

This is the story of how a seemingly sensible management decision about documentation has inflicted avoidable damage on a product. Read how the idea that “anybody can write” can backfire.

Best intentions

Imagine a software company. They decide to revamp one of their products. It’s gotten a little long in the tooth and deserves a renovation. Requirements and designs are written, modules are developed and tested. Documentation was previously understaffed, but that wasn’t a severe problem.

The shipment date approaches, and things get a little tight: Usability and performance tests lead to additional developments which lead to more tests. The flexible corporate culture pays off as they assign developers and testers from other units to revamping tasks. Meanwhile, documentation takes a backseat: Compared to development and test, it is less important for shipment, hence it is less urgent and gets less attention.

Original sin

Then the lone writer speaks up: He cannot keep up with more developers who keep changing the product at a more rapid pace. His manager has to watch the budget and cannot take on more people. So he does the most sensible thing. He breaks documentation into several tasks and assigns them to whoever has time and knowledge. After all, how hard can it be…?

So developers write online help. They build the windows and can explain how they work. Testers write the release notes. They test the changes and new features and can describe them. The lone writer writes the user manual and coordinates the other writing tasks.

And they launch on time, barely so, with a few glitches, but – phew.

Merrily chugging along

Fast forward, one year later. They develop version 2 of the revamped product. The lone writer has left. A tester will coordinate the documentation efforts. After all, how hard can it be…?

The online help and the release notes come off as before. No one has time to update the user manual, so they postpone it. From the manager’s perspective, documentation as a task works and makes it easier to distribute all tasks among all developers and testers.

Too late

One more year later, there are problems: After shipping version 2, customers started complaining that the documentation was incoherent. Some online help is more helpful than other entries. The release notes describe features that are neither in the online help nor in the manual. The documentation in general is now seen as a burden and a competitive disadvantage.

A business consultant takes a close look at the documentation and finds the complaints are justified. Much documentation focuses on features and reference information. Customers ask for workflows how to set up and operate the product, which is described in the outdated manual.

Lesson learned

As far as technical communication is concerned, I think there is a single simple lesson here: High-quality documentation requires a professional who is responsible and accountable, just as in development or test.

There are two reasons which I think managers should understand:

• To write effective documentation which can be maintained efficiently and used effectively requires experience and standards. To assign documentation as individual tasks creates incoherent, unmaintainable documentation with overlaps and gaps.
• As in development and test, what is seductive and cheaper in the short run, costs more money in the long run.

Beef up tech comm skills with free webinars

If one of your new year’s resolutions has been to improve your tech comm skills, here’s your chance. Industry experts offer several webinars in upcoming weeks to start you off. Many of them are free, so you really have no excuse! 🙂

Scriptorium

Scriptorium’s free webinars cover industry trends and technologies, such as:

• Content strategy in technical communication
• Trends in technical communication, 2012
• HTML5 and its impact on technical communication

I’ve attended many Scriptorium webinars and have learned a lot from them. They are substantial and presented well. If you’ve missed one, you can catch up on the canned recordings.

Oh, and Sarah O’Keefe, who does most of them, has just taken #2 on MindTouch’s list of the Most Influential in #Techcomm and #ContentStrategy.

Comtech Services

JoAnn Hackos’ free webinars (announced on the DITA Writer blog) are dedicated to moving towards DITA in a 3-part series of “Crossing the Chasm with DITA”.

Hyper/Word

Neil Perlin’s free webinars are usually more tool-oriented, so they’re hands-on training sessions on topics such as:

• MadCap Flare Mediums
• Using Help Authoring Tools as CMSs
• GUI Mobile App Authoring Tools
• Creating Mobile Apps with Viziapps
• Mobile documentation in Flare and RoboHelp

STC

STC’s webinars bring together the widest roster of industry experts, but they’re not free. They offer up to 3 webinars per week. Here are just the next six through the end of January:

• Mental Model Diagrams: Supportive Content for Specific Folks
• The Art of the Demo
• Getting Yourself Into Print
• Introduction to the Mobile Ecology
• Designing Quick Reference Guides
• Successful Strategies for Continuous Improvement

If you’re an STC member, sign up until January 31 and get $20 off on each webinar.

MadCap

MadCap’s free webinars are strong on tools and processes. Currently they only have one on offer about migration to Flare. But you can always check out the recordings for free. The tool-agnostic ones are quite valuable, even if you don’t use MadCap’s products.

Adobe

Adobe’s free webinars also mix tool-specific training with general topics. You do need an “Adobe Account” to register. Coming in January are:

• Key Trends in Software User Assistance: An Expert’s Perspective – Part 1
• Top 10 key trends shaping the Technical Communication industry of tomorrow: An industry research
• Why upgrade from older versions of RoboHelp (X5, 6, 7 or 8) to RoboHelp 9? What is the value proposition for your business?
• How to optimally leverage a Content Management System as a Technical Communicator
• What is the future of indexing for technical documentation?

If you know of additional tech comm webinars, feel free to leave a comment.