A common trouble with technical writing is the ability of the writer to connect to the end user. Because many technical writers are already experts in the field, they might not be able to approach the information from a completely new perspective, leaving readers feeling lost or confused.
But there are many ways in which a technical writer can ensure the writing addresses the thinking ability of the reader. Here are just a few:
(more…)
We all have goals in our lives, but what does technical writing have to do with goal setting?
Though the term ‘goal setting’ might not be used, the practice of setting goals can help clarify the ideas being presented in a document, and having a goal can make sure the writing stays on track.
SMART Goals Applied to Technical Writing
Using a common goal setting strategy – SMART – here is how technical writing can be made more effective:
(more…)
While you might already be an expert in technical writing, there is always someone else who is better informed (assuming you’re not the leading expert, of course) on the inner workings of what you’re documenting. These people are called subject matter experts (SME) and they’re an invaluable resource when you’re looking to create the most accurate documentation possible.
Where to Find Subject Matter Experts
(more…)
Because technical writing is a specialized field of communication, it’s clear that there are better ways to present information than you might with other types of written communication. Documenting processes and actions requires a very clear approach to writing, one that allows the reader to fully utilize the piece of writing for a particular result.
How to Present Your Writing
Using templates in technical writing is one way to make sure you’re creating a clear case for your chosen (or given) subject matter, but there are other ways to arrange your information so it can be used effectively.
(more…)
When you want to do something technical, you might look for instructions online. For example, if you wanted to build your own ‘Clapper,’ why not try to create this piece of convenient technology at home with a few pieces of seemingly basic tools?
In first stumbling upon this documentation, you might have thought you were onto something, but then you looked closely to see the limitations of technical writing for the masses.
The Clapper Instructions from Hell
(more…)
We all make mistakes when we write, but when writing technical documentation, small mistakes can add up to a large consequence – and they could even harm the user or the person on the receiving end. Since it’s about that time to make New Year’s resolutions, it’s a good time to remember common mistakes made in technical writing – and then promise not to make them next year. Here are seven mistakes to be watch for and avoid in the new year.
(more…)
When Stanford has something to say about technical writing, many of us eagerly listen. This academic institution is continuously questioning how things are done and how they can be done better – offering us an opportunity to grow. Even advice given back in 2006 as a discussion online can yield a wealth of tips for those interested in pursuing a career in technical writing, as well as for those interested in hiring a technical writer.
(more…)
Poll Results as of 12/9/2011
The Help Authoring Tools poll, featured in the left column of our blog, has been running for 3 weeks now. And though there have only been 94 voters so far, I thought it was a good time to look at the results and see if any trends can be spotted.
Madcap Flare Makes a Big Impression
Of the readers who have participated in the poll so far, just about 2/3rds (66%) are using MadCap Flare and another quarter or so (25%) are using RoboHelp, making knowledge of those two tools the apparent standard for help development – at least within the small sample of readers who’ve participated to date. Even with a small sample size, those numbers are impressive, especially for Flare, the relatively new kid on the block.
Dinosaurs to the Back of the Bus
FrameMaker and MS Word are tied with a usage rate of 10% each. That seems like a paltry number for those two tools, don’t you think? My understanding is that Framemaker remains the default tool for Department of Defense (DOD) projects, and traditionally has been more localization friendly.
Are Wikis the Future of Technical Communications?
Do you think wikis and wiki-enabling tools like Confluence are the wave of the future? Using a wiki for documentation seems like a good idea – at least on the surface. Wikis have the potential to allow users to help each other by filling in gaps in the documentation and providing shortcuts that the technical writer may not have considered. By tracking user updates to a wiki, you can get some valuable information on both the product/procedure and its documentation for future improvements. However, migrating content from a legacy system to a wiki would seem like a daunting project at best.
Help Wanted
Browsing through WAI’s current list of job openings for technical writers, I noticed three jobs specifically mentioned strong knowledge of MS Word and one mentioned Frame. None of the other postings mention any of the tools that are included in the poll. Yes, technical writers use a variety of tools for various tasks, including Visio and AutoCAD software, and those are mentioned occasionally.
I would still love to hear from those of you who already participated in the poll (and those of you who haven’t done so yet). I strongly suspect many of you use multiple tools – that’s why the poll was configured to allow you to vote for more than one. But I’m also interested in the difference between independent contractors, who may have to use a variety of tools throughout the course of a year for different clients/projects, and technical writers who are employed as full-time staff. Finally, we’d like to know the types of projects/deliverables for which you’re using the specific tools that received your vote. Please leave a comment (and get your friends to vote so we get a larger sample size) and let’s get a discussion going!
When it comes to technical documentation, most people would rather ignore the fine print and hope for the best. But when residents are faced with new regulations in their town, it seems that a different approach is needed. The students at Texas Tech in Texas decided to take their technical writing skills and create a user-friendly document for local residents. And isn’t that what technical writing is all about?
Helping Residents Understand
According to locals, the Lubbock Water Report has been a difficult subject with residents for years. While citizens want to learn more about their water supply and how it’s being handled, the dense materials in the report made that nearly impossible for anyone not already involved with creating this report. Students at Texas Tech’s 2011 Document Design course took the 2011 report and made it more readable. As a result, 70,000 residents were able to receive a new water report that was simple to read and easy to understand.
(more…)
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
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…)
