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!

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.

[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!

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.

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.

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.

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.

Content strategy can change tech comm in 2 ways

… and only one of them is up to us tech writers:

• Tech comm departments can engage in content strategy bottom-up, connect with stakeholders in training, customer services, marketing, and producct management to try to break down silos, reuse content and make content a corporate asset. One way to do this was the topic of Ray Gallon’s webinar “Content Strategy for Software Development”.
• Corporations can can engage in content strategy top-down and essentially change the way the organization works. The objective is essentially the same as above, the main difference is who’s driving it. While tech writers cannot do it without management support, managers may decide to relegate tech comms to one of many stakeholders – which I think would be a pity. tekom’s Content Strategy day offered several sessions which discussed corporate content strategies.

The “big disconnect” is closing

The “big disconnect” is the difference in IT innovation between consumer IT and corporate IT. Geoffrey Moore coined the phrase in an AIIM white paper and presentation: “How can it be that I am so powerful as a consumer and so lame as an employee?” Earlier, I wrote about exploiting the big disconnect as a tech writer.

The reason it’s closing in tech comm is that consumer web sites have appropriated help systems and all their benefits, so the use cases and business models finally catch up with user demands and technologies, as Scott Abel pointed out in his tekom keynote address.

Content migration is about people first

In summer, our team of writers embarked on the journey towards structured authoring. One of the surprises to me as we proceeded was that metaphorically speaking, for every hour I spend moving content, I’m spending another hour moving minds.

Your turn

What did you learn about tech writing in 2011? Feel free to leave a comment.

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.

Prerequisites

• Some knowledge of topic-based authoring. You should know the topic types you will use, for example, concepts, tasks and reference topics.
• Have a tactical framework. Ensure you know the documentation structure you aim for and how you will get there in a project. Consider for example the Top 4 tactics to structure legacy documentation.
• A style guide to which your documentation complies definitely helps.

1. Identify topic type(s) per section

Define each section in your manual as one of your topic types, for example, concept, task or reference.

If topic types are mixed…

A common problem at this point is that you may have topics that mix topic types. For example, your topic contains concept information and task information. Or task information and reference information. For details, see When topics don’t quite work.

2. Re-chunk sections to make them topics

Redistribute your content so each section becomes a topic:

1. Cut out everything in a section that doesn’t fit the selected topic type and put it aside.
2. Ensure that the topic that remains:
• Is either a concept or a task or a reference.
• Presents only one idea.
• Has only one purpose.
• Can stand alone, in context with others.
3. Take the content you have cut out and put aside and do one of the following:
• Integrate it into an existing topic where it fits better.
• Create a new topic for it.
• If it’s not relevant, throw it away.

If topics are too complex…

A common problem at this point is that you can end up with one or several topics that are too complex. Then you can try the following:

• If you can describe a topic’s content as two separate, but related ideas, turn it into two sibling topics.
• If you can fully summarise a topic’s content only as a very complex idea, turn it into a parent topic and create children topics for it.
• If it’s a long procedure with more than 10 main steps in a top-level numbered list, try to cut it into two topics approximately in the middle.

3. Re-sequence your topics

Re-arrange the sequence of your topics, so they flow nicely when users read not just one or two of them, but need to learn a complete setup or operational process.

1. Verify that your topics are in the best possible sequence and re-arrange them if necessary. You might want to try these categories:
• Setup, in the sequence of tasks.
• Operations, in the sequence of tasks.
• Reference topics, in alphabetical order.
• Concept topics can either appear as a section of their own, ordered from the large/general to the small/particular, or among the other topics as appropriate.
2. Verify that your topics are complete and add topics, if necessary:
• Do you have concept topics for all major elements in your task topics which explain what these elements are?
• Do you have task topics for all concept topics which explain how to set up and operate the elements

If the topic sequence doesn’t flow nicely…

A common problem is that the topics don’t flow as nicely once you have chunked them into stand-alone pieces. In this case, add some “glue” topics which orient readers and ensure a good flow, for example, at the beginning of chapters in books. Consider including these glue topics only in print deliverables; maybe they are not necessary in your online help.

4. Rewrite headings to guide readers

Often your legacy section headings work in the context of your manual, but don’t 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. Keep these guidelines in mind:

• Reflect the user’s need or goal in the heading.
• Phrase headings so users know what’s in the topic when they see only the heading in a link in another topic.
• Try to make headings unique so there’s no confusion when they appear in search result lists.

5. Add links between related topics

Ensure that your topics have links or cross-references between all related topics:

• Do your concept topics link to corresponding task topics – and vice versa?
• Do your task topics include or link to prerequisites and next steps?
• Do your task topics link to corresponding reference topics?

Your turn

Do you find these steps helpful? Have you converted documentation into topics before? Please leave a comment.