What’s in a tech comm blog? Top 10 posts from 4 years

For tech comm, blogs are a great medium to develop our profession, but also to archive knowledge and discussions.

I started Kai’s Tech Writing Blog 4 years ago, with a little fanfare:

Welcome to my new blog, yay! You’ll find my insights and experiences about software documentation here, what I’ve found to work and what didn’t. And some occasional wackiness.

Since 2010, the tech comm blogosphere (and blogs in general it seems) have been on a steadily declining slope. I think there are different reasons why tech comm blogs fade away:

• Some writers move on into other fields.
• Some find they have nothing more to say.
• Some stay in tech comm, but shift their priorities when the demands and responsibilities of their jobs increase.
• Some change their social media habits as they find twitter, Google+, LinkedIn or other services useful.

But the content in tech comm blogs is often still very useful, valuable and worth considering:

• When a question on methods or strategy pops up at the office or at conferences or webinars, I refer to “old” posts and often find them applicable, maybe after a little brushing up
• Old and recent posts on my own blog get a steady stream of readers as my stats indicate. There’s definitely a “long tail” over time to blog posts which proves their lasting value, if to niche audience. (There’s actually a short section on networks and crowds in the long tail on Wikipedia.)

See for yourself. Whether you’ve been reading my blog for a while or just found it a few weeks or months ago, here are 10 posts from the past which I still find useful:

1. Top 10 things that users want to do in a help system

Because a help system is like a library or a department store in a lot of ways.

2. 5 steps from legacy documentation to topics

Because moving from unstructured to structured documentation and topic-based authoring needn’t be difficult.

3. The curse and the cure for the ornery topic

Because topic-based authoring imposes a structure that doesn’t always sem to work.

4. Improve documentation with quality metrics

Because quality metrics for technical communication are difficult, but necessary and effective.

5. Top 4 steps to solicit perfect documentation reviews

Because most of us rely on subject-matter experts who don’t always have reviewing our content as their top priority.

6. Editing

7. Indexing

Because most of us are not done after creating content and getting it reviewed, we often need to edit language and provide index key terms for print output. Here’s how, along with links to resources I’ve found useful.

8. Getting ahead as a lone writer

Because it can be rough being the only tech comm’er in your organisation. My presentation slides link back to some posts to show you how you can improve documentation and raise your profile by adopting a few general management skills.

9. Ragged-right or justified alignment?

Because research is a better argument for your “alignment decision” than personal taste.

10. “The Creative Passion” guest post

This  is the one that started it all, my first post over at DMN Communications. It does show its age a bit, but it’s still the best piece if you want to know “where I’m coming from” and what makes me tick as a technical communicator.

Advertisement

EPPO redux or: Mark Baker is on to something

“For users, Every Page is Page One,” says Mark Baker. Users can land anywhere in your documentation and start consuming away. That’s why structured authoring is more than one method among many – it’s an imperative to create meaningful content and to stay relevant as a technical communicator.

Few technical communicators have recently chipped away at unquestioned conventional wisdom as profoundly as Mark Baker in his blog Every Page is Page One (EPPO). Here’s his thesis in a nutshell – EPPO redux, if you will.

The following is my boiled-down edit of the session description of Mark’s workshop at the Intelligent Content Conference yesterday. I can only claim credit for the mistakes and misunderstandings I introduced, but everything below is essentially Mark’s wisdom. I share it because I find it sensible and highly relevant – if you do, too, I encourage you to follow Mark on twitter and on his blog.

Writing Every Page is Page One Topics
Mark Baker, President, Analecta Communications Inc.

For users, Every Page is Page One. So write good Every Page is Page One topics, even when you have a large amount of related subject matter to cover. Construct information so readers can meet their information needs, no matter where they land. When covering a broad array of subject matter, don’t design the information to be consumed sequentially or hierarchically like a book.

Successful Every Page is Page One topics

• Define a limited purpose: Do one thing per topic, do it well and completely.
• Stay on one level: Be broad or be specific in a topic, but pick one and stick to it.
• Establish context: Orient readers so they know where they are.
• Conform to type: Orient readers so they know what type of topic they see, help the writer be consistent and complete.
• Assume the reader is qualified: To help readers get qualified offer links in a topic, not details.
• Link richly: Encourage the reader to explore, anchor the topic in its context.
• Provide the big picture: Create explicit high-level picture, don’t bury the big picture in the htopic sequence or hierarchy.

Tech comm communities are people, not tools

There’s not a single social media tool or channel that’s the vital “one-size-fits-all” connection for our diverse tech comm community, but it’s their combination that lets us thrive, as I’ve learned last week.

On Thursday, a colleague and I ran into an obscure problem with review packages in our help authoring tool, MadCap Flare. We didn’t find a solution in Flare’s online help, so I reached out to a user forum.

Peer/user forums

MadCap Software Forums are provided by MadCap, but they’re run for and by the community of MadCap users. I first searched existing threads to see if someone had encountered the same problem before, without success. But I did find a thread where two days earlier two users, V. and M., had run into a similar problem that we had also encountered – and solved.

In the communal spirit of give-and-take, I outlined our solution. (The trick hinges on knowing that Flare’s review packages are really zip files which you can unpack and manipulate – if you know what you’re doing.) Then I posted our own query.

Within 24 hours, M. posted three replies:

1. To confirm that our solution indeed works, at least in some circumstances – hence we were on to something useful that was worth sharing.
2. To post MadCap’s reply to her support case which essentially had the same steps as our solution – hence we got our DIY solution sanctioned by MadCap.
3. And to point out that our solution can also help us address our own problem – hence we basically couldn’t see the forest for the trees, and needed a fresh pair of eyes to consider our issue. 🙂

So it turned out that both my posts to the forum paid off. – But a small detail nagged me: M.’s greeting on the forum sounded like we knew each other, but her user name didn’t ring a bell.

Conferences

Flashback to October 2010, when I attended TCUK, the annual conference of the UK tech comm association ISTC. It was only my second tech comm conference, and the first one where I presented. My talk “Getting ahead as a lone writer” summarized my experiences and lessons learned when I had an opportunity – rather than the explicit task – to raise the quality and profile of the documentation. (You can also read about the talk in my earlier posts.)

I was really nervous the night before my talk and was very lucky to find a fellow tech writer and scheduled speaker to confide in. Karen Mardahl lent great moral and practical support. This chance encounter is another succes story: Karen has since become a good friend of mine – and most recently even a colleague!

My talk went well, and from comments I could tell that some tech comm’ers in the audience got something out of it, whether it was an ideas to try and implement or a more general sense that it might be possible and worthwhile to get ahead as a lone writer.

The feedback has been very helpful by reminding me that even minor points are helpful to some. And conversely, my biggest lesson may fall flat if no one has that same problem – or I don’t present it in a recognizable way… 🙂 Since then, I try to let conference speakers know when something struck a chord, whether it’s some practical advice or an alternative perspective on things.

Mailing lists and groups

As a member of ISTC, I get a daily digest of the association’s mailing list. I must admit I haven’t gotten a lot of use out of it so far. Maybe it’s because much content is specific to the UK, such as meetings of area groups. But Friday’s digest had an entry that merits its mention here: M. had posted, using the same user name as on the Flare forum and her full name.

Now I knew who it was: One of the attendees of my talk at TCUK 2010! We had been connected on LinkedIn for a while, so I sent her a message to thank her for her advice.

It’s the people, not the tools

I sometimes think that the tech comm blogging scene may be slowing down. At other times, I wonder if I really need yet another mailing list. But as last week’s experience has taught me, different channels have different uses to connect me to other tech comm’ers. So ultimately, it’s not about this channel or that app – it’s about connecting with people. And I, for one, am glad, proud and humbled to be part of such a vital professional scene which is stronger than any one channel.

Address information overload in tech comm

Addressing information overload helps your user assistance succeed when knowing your audience and offering correct and concise content is not enough. You can have great topics well-written and well-structured, if they’re part of an information deluge, they won’t help your users get their stuff done.

I take my cue from a post by Nathaniel Davis over at UX matters called “IA Strategy: Addressing the Signatures of Information Overload“. Nathaniel describes six such signatures. I think at least three of them have something to say why and how too much information fails in documentation, too.

1. Feedback

Feedback is the essential reality check to determine whether users suffer from information overload. Customers may report that they’re not sure they’ve found the right information or they cannot apply it efficiently. Even if the content is fine topic by topic, the bulk of information is unmanageable. In this case, consider improving search and browsability for more efficient use of the documentation.

2. The utility gap

The utility gap means that customers only use a small fraction of all the information they have at their disposal. As Nathaniel says, it’s what I have vs. what I use.

If certain user types experience utility gaps, consider addressing them with special documents. For example, you could assist novice users with a quick start document. Or address a special use case which only requires one of the many processes, plus some reference information. With topic-based authoring, it’s usually easy to create such additional documents by re-using the relevant topics. (Maybe add one or two specific “glue topics” to make sure the new document still flows nicely…)

If all users experience utility gaps, consider progressive disclosure by layering your content. The benefit of offering all content within three mouse-clicks wears off if it’s too much. Progressive disclosure structures content by providing the most essential, most frequently used topics first and more obscure information later. Make sure, however, that all topics remain searchable and findable!

3. Filter failure

Filter failure means that users lack ways to judge which information to trust and use. It’s what I can use vs. what I should use. Filter failure can be solved with tools and with content.

Customers who are confident to use their own judgment require tools to filter information. In documentation, faceted search allows users to reduce search results by categories to weed out inapplicable information.

Customers who prefer to rely on expert judgement will benefit from recommendations in the content itself. Consider adding such recommendations for certain user roles or use cases to guide customers to the most suitable information.

– Have you had symptoms of information overload in documentation? Would these strategies help users to cope? What other solutions are there? Feel free to leave a comment.

Welcome to summer reruns, episode 2

My blog and I are taking it a little easier for a couple of weeks.

I’ve had a wonderful time with this blog so far, and I thank each and every one of you for reading, lurking or commenting. I’ve learned a lot from your comments, and I appreciate your support! It’s been a walk on the beach… 🙂

As I’m gearing up for the new season, here are some reruns from the 10 most popular posts.

Improve documentation with quality metrics

… in which I argue that quality metrics for technical communication are difficult, but necessary and effective (complete with a picture of the seal of quality!).

How and why to estimate writing efforts

… in which I explain why, what and how to estimate efforts and deadlines in technical communications.

Top 10 reasons for tech writers and trainers to collaborate

… in which I give eight reasons why technical communicators can and should collaborate with trainers – and two why they cannot afford not to do it.

Welcome to summer reruns, episode 1

My blog and I are taking it a little easier for a couple of weeks.

I really enjoy writing posts, hearing from you and keeping in touch with other tech comm’ers from far and near. And I thank every one who’s stopped by to chime in or just to read! I keep learning from your comments, and I appreciate your support! It’s been a warm summer’s breeze… 🙂

As I’m gearing up for the new season, here are some reruns from the 10 most popular posts on my blog.

Top 10 things that users want to do in a help system

… in which I draw parallels between a help system, a department store and a library to illustrate how customers want to navigate each one.

Top 3 success factors in online help systems

… in which I apply some of Cameron Chapman’s “10 Usability Tips Based on Research Studies” to online documentation and come up with factors that can make or break help systems.

Top 4 benefits of writing a tech comm blog

… in which I celebrated my blog’s first anniversary, reminiscing about the various ways it’s been good to me – and continues to be!  🙂

Advice about breaking into tech comm

Some time ago, a lab technician asked me how to go about breaking into technical communications. I’ve already replied to J privately, but I thought the issue could be of interest to you as well, so here’s J’s question and my reply, both edited for publication.

J wrote me:

I’ve recently become very interested in the Technical Communication field. Currently, I’m working as a lab technician for laboratory machinery which can sometimes be very difficult to operate.

I’ve been spending more and more of my time poring through technical instructions, talking to sales associates, and transcribing everything into easy-to-understand instructions to be used by my co-workers. This has expanded to the point where I break down complex laboratory procedures, peer-reviewed studies, etc. into something my co-workers can understand.

I really enjoy this sort of work and would like to make a full time career out of it. But I don’t know where to begin.

Ideally, I’d like to begin by doing this sort of writing as a freelance gig and slowly build up my business until it affords me a comfortable living.

What’s the best way to get started? Do tech comm writers typically work freelance or are they typically full-time employees for a particular company? Can you recommend any websites or books that might help me out? How do most people in the Technical Communication field make their money?

And I replied:

Hi, J,

From what you tell me, you’re on a very good way to becoming a technical communicator, for two reasons:

You focus on users. In my experience, it’s essential to have the right perspective in that job: To understand the users and to make sure they can do their jobs well. Many tech writers get bogged down by the systems they describe and their features, because they’re right in their faces. Of course, knowing these is important – but your first obligation should be to your users. They are your customers, whether they are inside your company or outside.

You have strong domain knowledge. Many tech comm’ers either have a strong writing background (and a liberal arts degree, like I do in American Studies), or they have, loosely speaking, an engineering background. You’ll find your background valuable in 3 ways:

1. You’ll need it to get respect from your peers, whether you collect information from them or ask them to review your documents.
2. You’ll gain trust from your readers/customers, when they realize you speak their language and know what you’re talking about.
3. It will help you with managers who often appreciate domain knowledge over writing skills, if only because they think that “anybody can write”.

A general disclaimer before I go on: I’m afraid I don’t know the US job market nearly good enough to offer reliable advice. I’ve gone to school in the US, and know some tech comm’ers there, but I’ve never actually worked in the US. So I can’t really advise you on the freelance vs. employed question. My impression is that it seems to be pretty difficult to go the freelance route when you’re just starting out…

That said, there are really both scenarios:

• Self-employed tech comm’ers often appreciate setting their own rates and hours and the mix of topics they cover. But it’s difficult to build a customer base that keeps paying your rent.
• Employed tech comm’ers have a regular paycheck, but many complain about being awfully low on the corporate totem pole/food chain. Unless you establish good rapport and earn respect (which is hopfully easy for you thanks to the two reasons above), you might find that many colleagues and managers don’t really understand what you do, how you add value to the company.

Two books I’ve found especially helpful are:

• Developing Quality Technical Information is good and relevant, even though it’s 7 years old. It’s basically a gigantic, well-argued check list with lots of good examples. If you only were to read a single book on tech comm, I recommend this one.
• DITA Best Practices came out about half a year ago. This is a very good book if you publish any kind of online documentation, whether you follow the DITA standard or not. Chapters 1, 2, 3, 4, 7, and 10 are about topic-based authoring, specifically about designing, writing, linking and editing topics. It’s a very instructive hands-on book with lots of examples.

Online resources are plentiful, I recommend you start with:

• Tom Johnson’s blog I’d rather be writing. He’s the most visible tech comm blogger and has been helpful in the past, answering questions about breaking into tech writing. Lately, he’s opened up a few such requests to communal answers. If you don’t get a direct answer from him, I think you’ll find his past posts and their comments helpful. Plus, he’s based in the US!
• Social networks are nicely summed up and compared in Bill Albing’s post “How social can we go”. I like ATC and TWW.
• Twitter is also a massive hangout for tech comm people. These two lists are a good start to follow us around.

I hope I could give you some ideas and helpful advice. I wish you good luck in what I think is an exciting profession!

All the best, Kai.

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!

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.