Skip to Content Skip to Main Navigation
 

Posts with the Tag: technical communications

Technical Writing in the Trump Era

10th April 2017 Posted in Blog, Writing 0 Comments

Image for Technical Writing in the Trump Era Post

Guest post by Gill Kohn

Happy New Year Charlie Brown from Mar-A-Lago

Welcome to Donald Trump’s America! It’s not exactly Norman Rockwell, some might say more like Andy Warhol. Nothing is as it looks, cinema verite’ with a twist: often appearing larger than life and then distorted for full effect. As the Federal courts argue the constitutionality of President Trump’s recent landmark executive order on immigration, we can begin to see the attention being paid to drafting and control over official documents under the current administration. Words must matter to now President Trump, as with the original response from the White House referring to the temporary restraining order from the Ninth Circuit presiding over Washington State as “outrageous”. This response was immediately walked back and the word “outrageous” omitted. However, his characterization of U.S District Court Senior Judge James Robart as a “so-called judge” was left in place, much to the dismay of several of his closest advisors. The good news, not “fake news” for President Trump, is that (more…)

A Creative Way to Teach Technical Writing

23rd October 2014 Posted in Blog, Communication, Training Programs 0 Comments

technical-writing-how-to-862490-211x138
As any former technical communications student can tell you, in the hands of the wrong professor, technical writing subjects can seem dry, abstract, and even boring at times. That’s why this recent article on The Western Front drew our interest. The article features English professor Michael Bell, and his teaching methodology for his English 302 class, Introduction to Technical and Professional Writing.

Bell has his students write instructions and rules for a game they create. He points out that “If a student is able to write a set of rules for a game, they’ll know how to write a professional document.” Makes sense to us. The benefits of such a teaching method include:

  • Classmates get to play the game and then give feedback on how easy it was to interact with the game manual
  • By working with a game, students are more inclined to not only have fun, but to make sure it works as described
  • Because games are something tangible students can readily relate to in the real world, class concepts don’t seem so abstract
  • It allows students to focus on a single project while still coming away with the principles and concepts of the course

Bell found that by allowing students to learn old concepts in a new way, they cared more about the work they did instead of viewing it as just another assignment. When students care about – and can feel a passion for – what they are doing, the result can only be positive. Don’t you agree?

What are your thoughts on Bell’s teaching method? As a teacher or student of technical communications subjects, have you experienced similar methodologies or other approaches you felt were very effective? Please leave a comment, we’d love to hear your thoughts.

Technical Writing for Copywriters

29th August 2014 Posted in Blog, Writing 0 Comments

Image for Technical Writing for Copywriters

Copyblogger recently featured a post by Nick Chowdry titled, “Clueless About Technical Writing? Get Started With These Essential Tips.” In the post, Chowdry offers tips for copywriters who may be faced with their first technical writing assignment.

Chowdry’s tips are on the mark and include:

  • Getting to the point quickly (terseness is a virtue)
  • Simplify your language (look for simpler words that mean the same thing)
  • Keep structure in mind (he suggests an inverted pyramid)
  • Use layout to your advantage (lists, of course, but consider using a professional designer for layout?)

We think one important tip Chowdry left out is to use graphics or images to help convey your message. Yes, he touches on it, but pictures, diagrams, screen captures, etc. are worth a thousand words when it comes to technical writing. Sure, he mentions inforgraphics, but most infographics are designed to stand on their own. So many product guides today are nothing more than a sheet of illustrated steps with no text. The added benefit is that this makes translation/localization a whole lot easier, if not totally unnecessary. But if that was the desired deliverable, it’s more likely an assignment for an illustrator than a writer.

Another point left unmentioned is to consider your audience. Technical publications need to be suited for the level of technical knowledge of the reader or user. Maybe that was too obvious to mention, since all writing needs to be tailored its target audience.

All in all, Chowdry’s post contains some valuable – if not common sense – tips. We think design concerns are largely driven by the publishing medium, the length of the piece and any client design requirements in place.

What are your thoughts? If you are a technical writer, what advice would you give a copywriter when facing his or her first technical writing assignment? Please leave a comment.

Trends in TechComm Tools

14th August 2014 Posted in Blog, Technology & Tools 0 Comments

toolbox1185442_41926391-230x137

Technical Writer Tom Johnson recently wrote a two-part look at the fragmentation or ‘diversity’ of tools used by technical communicators today. The topic focused around the vastly different tools in a technical writer’s/technical communicator’s toolbox today and whether a standardized tool set or a diverse set of tools has the advantage.

The recently published results of the Writers UA 2014 User Assistance Tool Survey seem to confirm the divergence that exists in technical communications tool usage, at least within the software user assistance community.

In his first post, Is Tool Fragmentation a Good Thing?, Johnson looked at the pros and cons of tool fragmentation as well as the role played by DITA in such fragmentation. While DITA is growing in popularity, the tools used to implement it vary widely.

In part 2, Benefits of Tool Diversity, Part II, he makes the point that standardization can have obvious strategic benefits, but it also encourages stagnation and hampers creativity and agility. Unfortunately, HR managers often over stress tool knowledge when it comes to screening technical communicators.

What’s in your technical communications toolbox? Do you believe it’s better that the technical communications profession employs a diverse set of tools or would you like to see more standardization when it comes to tool adoption? Please leave a comment.

The Power of One, Seemingly Unimportant, Word

5th July 2014 Posted in Blog, Documentation 0 Comments

Image for Should Technical Writing Be Creative

Words are powerful. Headlines, tweets, you name it. The addition or omission of a single word can give your audience an entirely different perspective on the topic at hand.

We subscribe to Sarah Maddox’ excellent technical writing and fiction blog, FFeathers, and get an email notification when a new post is published. Recently, we received such a notification in our inbox with the subject line:

[New post] Documentation developers need to do their jobs

Our first thought? Maybe this was a critique of documentation developers who aren’t doing their jobs properly, who needed to buck up and get with the program. Seemed interesting enough. Previewing the post in email displayed the same title. But reading beyond the title revealed this wasn’t a critical piece at all. Instead, it was a post about the types of documentation that developers need to do their jobs properly.

Clicking through to the post on her blog revealed a slightly different title for the post:

Documentation that developers need to do their jobs

Well, yes. Exactly. Great, useful post. And really, even the email subject line and post title could have been interpreted either way. We are in no way criticizing Sarah, just making an observation on the power of words. We continue to highly recommend her blog, and we are long-term happy subscribers. In fact, we tweeted it to our followers. Read the article.

All of that got us to thinking about the difference one word can make in interpreting the context of a sentence or a title. In this example, a seemingly unimportant word that carried so much weight – that. A word that some grammarians/instructors even suggest you try to omit. What are your thoughts?

What examples have you seen where one word can convey an entirely different meaning? Do you now feel any differently about “that”? Is it more of an issue with today’s nanosecond-short-attention-span audiences? Please leave a comment.

Is the Importance of Technical Communication Evolving?

20th June 2014 Posted in Blog, Documentation 1 Comment

Image for Technical Writing Impact on Business

This excellent summary article on TC World makes the assertion that:

“Technical communication is moving away from engineering and closer towards marketing and communications.”

The piece cites and summarizes the results of surveys to back up that claim with three overall observations:

  1. Good product information encourages users to recommend a product.
  2. High-quality technical information is a decisive factor in purchasing decisions.
  3. The vast majority or consumers research online before buying.

We don’t think the third item is a surprise to anyone. Researching online in advance of making a purchase is pretty much a given today. But have you given much thought about the extent to which technical communications can influence purchase decisions and grow sales?

Some of the findings include:

  • More respondents (47%) used product information to learn more about a new product before they used it than to troubleshoot a problem (42%).
  • 82% of those surveyed felt that high quality product content was essential to good customer service.
  • 88.7% believed that high quality technical information is important or very important with regard to the purchase decision.
  • 72% responded that high quality product content makes it more likely that they would recommend a product and brand.

Are any of these findings particularly surprising to you? What are your thoughts?

Related topic:
Great Documentation Can Save You Big Bucks When it Comes to Support

Is the Future of Technical Writing in API Docs?

5th June 2014 Posted in Blog, Career Development, Documentation 0 Comments

developer-docs-230x72-467965_61936356

Over on his I’d Rather Be Writing blog, Tom Johnson recently published a post titled, “The Future of Tech Comm is Developer Doc“. Johnson has a point in that yes, it’s true that the latest mantra is pretty much “If an end user needs documentation, your app/program/whatever is not user friendly.” Okay, we guess. After all, end users aren’t know to even bother looking at documentation – they’d rather go through trial and error, pull their hair out and then get help through tech support or by consulting with another user.

But technical writers who can write developer docs have been in greater demand and have commanded better hourly rates and annual salaries for years. That’s because it’s harder to find experienced technical communicators who are actually comfortable with developer documentation or who have sufficient understanding of programming languages to communicate effectively with a developer audience.

That’s probably why developers are often called upon &emdash; or make the conscious decision &emdash; to write the docs themselves, which is certainly not an ideal situation. Don’t believe me? See Why Developers Write Horrible Documentation.

So does the future for technical communications professionals lie in developer docs? Well, you could probably make an argument that Johnson is a bit biased since he admits most of his work is in the SDK and API areas. You could also make the case that he has a first-hand point of view on the topic. But we think technical communicators who can effectively document APIs to a developer audience have always been in greater demand, so there’s nothing really new. Or is there?

What are your thoughts on the future of technical communications? Is it time for technical writers to grab the bull by the horns and learn how to write developer documentation? Please leave a comment, we’d love to hear your views.

What Courses are Needed for Technical Writers?

22nd March 2014 Posted in Blog, Career Development, Technical Writers 0 Comments

technical-writing-how-to-862490-211x138

Entry-level technical writers and those who are considering technical communications as a career often ask if it’s necessary to get a technical writing certification or if certain courses are best to improve their skill set and hireability.

Ask five people and you’ll likely get five different answers. Recently, I’d Rather Be Writing posed this question to Laura Palmer, an assistant professor at Southern Polytechnic State University in Marietta, Georgia. Her response, although somewhat inconclusive, is a good examination of how to prepare academically for a career in technical communications, including not only a look at course work but at textbooks, too.

Read: “The Courses Conundrum: What Do You Need to Be a Technical Communicator?” for her detailed response. If you’re already a technical communications professional, we’d like to hear about your first-hand experiences, so please leave a comment below for discussion.

Related topic: Which Skill Sets are Important for a Technical Writer?

Confessions of a Quality Queen: Getting Good Reviews in Bad Times with Remote Teams

22nd November 2011 Posted in Blog, Documentation, Industry Articles 0 Comments

Editor’s Note: This was the feature article in this month’s TechCom Manager newsletter, reprinted here with permission. Click the previous link to subscribe to the newsletter.

Luanne Oleas, Author of Confessions of a Quality Queen- Getting Good Reviews in Bad Times with Remote Teams

Luanne Oleas

The projects, they are increasing. The number of writers is decreasing. Jobs are floating across oceans. Agile, thy name is fickle. What’s a good writer going to do? You have to change. Adapt. Be ready for anything, because chances are, that’s exactly what’s coming your way.

One of the hardest principles slipping from our grasp in these tense times is the quality factor. It used to be one area where the technical writer could be the master of his or her fate. Developers revised your content, project managers overruled your phraseology, but you, as an experienced writer, could still make the final product shine. Now? Not so much.

Part of the problem could be that your Subject Matter Experts (SMEs) are no longer sharing your water cooler. In fact, in this year’s budget, they nixed the water cooler, too. Your reviewers could be thousands of miles away, which can make motivating them difficult. OK, impossible. Well, almost.

(more…)

Why Technical Communication Managers Need to Manage Terminology

Editor’s Note: This was the feature article in this month’s TechCom Manager newsletter, reprinted here with permission. Click the previous link to subscribe to the newsletter.

Val Swisher , Author of Why Technical Communication Managers Need to Manage Terminology

Val Swisher

If your company is like most these days, you have been tasked with creating more (and more) content with fewer (and fewer) people. In the never-ending quest to cut expenses, many companies have laid-off content developers. At the same time, in the quest to drive revenue, companies are shipping more products, in more languages, and at a more rapid pace. That begs the question, “How do you get more out of the same resources when you create content?” Resources are both the people who create and edit the content, and the content itself. When it comes to increasing operational efficiency, companies can do several things to enhance their content output without adding more resources.

(more…)

Page 1 of 212