Find more tech comm blogs

If you enjoy this blog, you can find more reading like it on the list of “20 Helpful Blogs for Technical Writing Students” put together by the folks at onlinecolleges.net.

The list contains many of the blogs on my own blog roll, and it’s short and concise enough so you can quickly pick up a couple of new sites for your feed reader.

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.

Happy New Year

I wish you a happy new year and all the best for 2012!

2011 in Kai's Tech Writing Blog, fireworks graphics

If you’ve stopped by this blog in 2011, you’re in the good company of readers, most from the USA, Germany, Canada and the UK, but also from India, Denmark, Philippines, Australia, South Africa and Brazil – and other countries who didn’t make it into the top 10.

Visitors to this blog came from the USA, Germany, Canada.

I hope to see you around in 2012, on this here blog, on twitter at @techwriterkai or on the occasional conference: I will speak at STC Summit in Chicago in May, and plan to attend – speaking or not – TCUK and tekom in October.

Top 5 tech writing posts in 2011

Here are the 5 most popular posts on Kai’s Tech Writing Blog in 2011. After my Top 3 tech comm lessons, this is the second “year in review” posts.

Kai’s Tech Writing Blog takes a break now and will be back in 2012. I thank each one of you for reading and commenting; I’m happy and proud to be part of such a stimulating professional community, and I’m a better tech writer for it!

5. 2011 megatrend in technical communications

In January, I mashed up three predictions by Sarah O’Keefe into one megatrend:

I think this year’s megatrend for technical communicators and their managers, especially employed ones, is to position tech comm as a business in its own right – or to be redundant in the long run.

4. Learn about DITA in a couple of hours

I still think the best way, if you have two hours, is to read Ann Rockley’s DITA 101, second edition, which I reviewed:

The book excels in firmly embedding DITA’s technologies and workflows in the larger context of structured writing and topic-based authoring. … I recommend that you read it if you are involved in a project to implement DITA, writing or translating documentation in a DITA environment or managing technical writers

3. Improve documentation with quality metrics

This is my only post this year with a visual cue inspired by a Marx Brothers’ movie! 🙂

Quality metrics for technical communication are difficult, but necessary and effective. They are difficult because you need to define quality standards and then measure compliance with them. They are necessary because they reflect the value add to customers (which quantitative metrics usually don’t). And they are effective because they are the only way to improve your documentation in a structured way in the long run.

2. 5 steps from legacy documentation to topics

The company I work for set off to migrate its documentation to topic-based authoring:

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.

1. Top 4 benefits of writing a tech comm blog

As I entered my second year of blogging, I reflected on the reasons and benefits of Kai’s Tech Writing Blog:

1. Improve ideas
2. Connect with the community
3. Picture progress
4. Write regularly

Your turn

What was your favourite tech writing blog post, on this blog or elsewhere? Feel free to leave a comment.

Art vs. online: 2 dimensions of curating

Curating is a cool word, or trendy jargon, for what happens in web technologies and in art museums, but they are fundamentally different activities.

In this post, I want to add an alternative view to Rachel Potts who recently wrote about “When software UX met museum curation“. Where Rachel emphasises similarities, I’d like to focus on the differences, especially as they relate to art museums.

Your artefacts

One serious limitation and difference in curating at art museums, compared to anything in software and online, is that you need to care for original, unique works. If you mount a special exhibition, you need to procure them to begin with. And sometimes you cannot get them, no matter how much you want them in the show to present an artist or an era in history or to make your case.

  • Some works don’t travel because they’re fragile or because the insurance is too costly or because they’re centerpieces in the collection that owns them.
  • Some owners won’t lend works to you, because you cannot satisfy security requirements or because you’re too small a museum or because they don’t like your director.
  • Some works are simply lost.

Of course, you can always do with fewer or lesser works or, in the case of historic artefacts, with copies, but that invariably hurts the critical response and your attendance.

"Stalking Christina" - other people regarding my favorite painting

Your objectives

Another difference is that for many art museums “enabling users to learn” is one objective among many. And several other objectives are, unfortunately, at odds with it:

  • Some pieces are too sensitive to light or touch or movement to allow more than very few people to experience them.
  • Some museums need to please or placate donors (who may influence what’s shown and what not) and trustees (who may influence what gets paid for and what not).
  • Some museums don’t have the means: They lack the manpower to accommodate visitors more than a few hours per week. Or they don’t have the expertise to allow them to learn well.

Your audience

A third difference is that art museums who put on ambitious, critically well-regarded exhibitions find that attendance is surprisingly low. The reason is simple and disappointing: Many people don’t want to be enabled to learn in art museums. They don’t want to learn new things, much less have their beliefs challenged. Instead, many people visit an art museum, because of the way it makes them feel:

  • Many go to be in the presence of beauty or to be awed. Hence the success of any show whose title mentions a best-selling artist or any of the words “Impressionist”, “Gold” or “Gods” – even if the title is far-fetched and the show mediocre at best. “Dinosaurs” gets kids, and anything that flies or shoots gets their dads.
  • Some go to feel cool. Hence the success of after-work parties in modern art museums.

The words

Roger Hart once told me, it’s futile to try to stop linguistic change. And the web is a great change agent of language:

  • How many kids today know that women warriors (or a river) gave their name to an online store?
  • The German language has known about “email” for centuries (though we only spell it thus after a recent change in orthography); in English, it’s known as “enamel”.

But if language is to represent the real world, I advocate to respect the differences within one word, such as curating. Conflating two similar activities into the same word cheapens our experience of the stuff that surrounds us.

Tech comm meets content strategy, with Ray Gallon

Technical communications and content strategy have a lot to say to each other.  Bloggers have frequently related the two disciplines. Tech comm conferences run streams on content strategy, for example, tekom11 dedicated a whole day to the topic.

Content strategy for software development

Ray Gallon at tekom. Photo by @umpff, used with permission.

Ray Gallon at tekom. Photo by @umpff, used with permission.

Leave it to Scriptorium and their excellent webinars to shed some light on the situation. Recently, they invited Ray Gallon to present his “Content Strategy for Software Development“. (To learn more about Ray, read his recent interview over at the Firehead blog. Or you can check out the very similar presentation which Ray held at tekom.)

Ray’s presentation was very enlightening to me, because he applied content strategy to software development. I create documentation for software applications, so I can relate to creating content for them. In the following, I’ll mainly focus on the first half, but I recommend watching the entire webinar.

Software development as information-rich environment

For the sake of his argument, Ray set the stage by looking at (complex) software developments not as products or tools, but as information-rich interactive environments. Software could thus be an expert system that supports users to make an appropriate decision, e.g., a medical diagnosis.

The first question to content strategists is then: What does the user need from the software? There are several answers; the user may need to

  • Know something (relating to concept topics)
  • Do something (relating to task topics)
  • Explore or understand something
  • Integrate or combine the software with his other tasks and processes

Plan to help your users

Ray then presented several document types which help content strategists to plan how they can best support users in their tasks and decisions. Among them was the Content Requirements Worksheet:

Ray Gallon's Content Requirements Worksheet

Ray Gallon's Content Requirements Worksheet explained. Click to enlarge. (Pardon the mediocre quality; prezi > WebEx recording > SlideShare is one compression too many...)

This document was a real-eye opener for me. It represents a holistic view of all user-facing content in a software application:

  • Informational, editorial content
  • Structural software content, such as user interface messages
  • User guidance, such as tool tips, help screens
  • User decision support to help users do the right things for the right reasons
  • Dynamic content, such as search results
  • Live interactive content as preesented in forums and social networks

Content workers, unite!

The Content Requirements Worksheet can be very beneficial to future users of a software. But it presents a challenge to content strategists to get a wide variety of requirements right. That is the opportunity for technical communicators and user experience designers and information architects to pool their skills and join forces.

As Ray said in his comment to my previous post:

Many tech comms do a bit of, or a lot of, content strategy in their work, and if an organization has a content strategy then everyone, tech comms included, needs to understand it and be on board.

So let’s transcend the silos of our systems, their manifold features and the artefacts we’re used to creating. Let’s start with good, thoughtful design from which our users benefit.

Your turn

Is this a good way to relate content strategy to technical communications? Or do you know better ways? Feel free to leave a comment.

All aboard! Onwards to structured authoring!

Our team of technical writers is embarking on a journey towards structured authoring. With 10 writers, we’ll move from an unstructured Word to PDF/CHM environment to a structured Flare to WebHelp/PDF environment. Or I should say “semi-structured”: We do have an information model based on DITA, but we won’t actually be able to enforce it with Flare (which we knew before we chose the tool).

It’ll be an interesting cruise, to be sure! Four writers already apply topic-based authoring rather than the previous free-form documentation guided mainly by common sense. The others have had training, but no real opportunity to write topics continuously. We have drafted tighter new processes to draft, write, review and edit topics to replace the previous loose processes of writing and reviewing, but they are not in place yet.

And then there’s the new tool, of course. Only one of us has worked with Flare before. Many of us are excited about getting Flare. Some really like it – what we’ve seen in several demos so far. Others just really loathe the current writing environment.

“Regarding the pain of others”

So as we’re about embark, I’ve been looking out for others who’ve taken the trip before. Scriptorium’s State of Structure webcast has been very helpful: Its results of a survey among 200 tech communicators helps to position us in relation to others who are currently implementing structured authoring or considering it. It also collects some mistakes respondents have gone through. I’ll just be quoting a few select points, but the whole webcast by Sarah O’Keefe is totally worth checking out, so thanks to Scriptorium for making this webcast available!

Reasons

The top reasons why survey respondents (consider to) move to structured authoring made us nod emphatically: Reuse, consistency and cost savings are also at the top of our wish list of achievements. Looking ahead, it’s promising that the majority of respondents achieve these goals.

We’ll also take other goals that respondents achieved, whether it’s to automate processes or to reduce content (oh, yes, please, we’re not even exactly sure how much redundant, almost identical content we have). So far we’re confident, we’re not only doing the right thing, but doing it for the right reasons, too!

Efforts

Savings have their own price, of course. Sarah’s survey confirms several cost points we’ve already identified in the project.

  • Converting legacy content is a biggie for us, simply because we currently have a lot of stuff.
  • Redefining output layout will take time, but will be worth it given what Flare is capable of doing with CSS in both web and print outputs.
  • Integrating a new system with its writing and publishing processes into our product and workflow systems will also take some time.

Mistakes

Mistakes have been made by others before us, and we’ll have plenty of chances to make our very own mistakes. If we’re lucky, we can avoid repeating the mistakes of others:

  • Planning and project management cause problems, maybe because most companies lack the experience of major documentation overhaul projects. Sarah specifically mentioned the lack of understanding of the project scope and of the need for testing. So we’ll look through our project plan again and ensure that the estimates are plausible.
  • Converting legacy contents can also get you into trouble, especially when you convert something that’s less than structured. It doesn’t help if you reserve too little time to do it or get inexperienced people to do, whether it’s off-shore labor or student helpers. That’s sound advice: GIGO (“garbage in, garbage out”) can certainly endanger the expected benefits. A new tool can help us be more efficient, but we still have to learn and apply structured writing in topics. So this confirms one of my two tech comm dogmas: Don’t get a new tool to fix your processes!

Setting out

What do you think? Is our crew well-equipped, given a tried and proven method, well-defined processes, a new tool and the words of warnings above? If you have additional advice, please leave a message.