Kai’s Tech Writing Blog is 2 years old!

Kai’s Tech Writing Blog is 2 years old now – and it’s pretty amazing to me…!

When I started blogging, I had no idea what it means to write publicly and (sort of) regularly about tech comm. And it’s been great, mainly thanks to you, my readers and followers:

• 148 posts have made it worthwhile, because I know each one was read, many were tweeted about and commented on.
• 280 comments from you have been a great help in becoming a better writer.

Thanks for reading and commenting and generally being a great diverse community. I’m glad and proud to be part of y’all!

Advertisement

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.

On being a tech comm influencer

MindTouch’s list of The 400 Most Influential in #Techcomm and #ContentStrategy does a great job of invigorating our profession, but has a few problems as well.

[This blog post is victim to my regular blogging schedule: It was written before, but published after David Farbey’s more elaborate post where all the action is in the comments and Aaron from MindTouch replies to some of the issues with the list!]

Here’s my play-by-play recap of my various reactions to the list:

1. Hope — “Did I make the top 50?”
2. Marvel — “Wow, look at the people at the top, they’re my #techcomm heroes, my personal all-star list!”
3. Reality check — I came in at no. 69.
4. Contentment — “Yeah, that’s a fair ranking, given my adjacent fellow influencers…” 🙂
5. Wonder I — “‘Influencer’? Is that even a word?”
6. Wonder II — “How did they come up with this ranking?” The accompanying process post isn’t none too clear how the ranking came about. MindTouch told me: “Yes, the social analysis tool used currently primarily analyzes twitter, but blogs also are a factor.”
7. Joy — “I can totally extend my network and add people I’m not following yet!”
8. Doubt — “Many people on the list don’t tweet a lot or have practically stopped months ago. Is it really worth following them (okay, it doesn’t cost anything if they don’t tweet…)?”
9. Scepticism I — “Maybe the process needs some refinement before it produces a meaningful long tail – or maybe 400 is a bit too long?”
10. Scepticism II — “Huh, here’s someone tweeting in Spanish – but wait a minute, just about anyone else on the list (myself included) writes in English. Where are the other languages?”

On the whole, I think it’s a great service to the profession:

• It’s galvanizing the community – and I hope it doesn’t alienate anyone (well, except Scott Abel, maybe, who wasn’t on the list – because he deserves the special mention as 2011 Internet Influencer… 😉 )
• It’s boosted my twitter readership, active & passive, more than any other single event!
• … and nobody else does something like this.

So thanks, MindTouch!

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.

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!

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.

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.