Search results

An Interview About Technical Writing

by Tom Johnson on Oct 9, 2009
categories: beginners technical-writing

Listen here:

This is a special podcast for Carly Finseth at Clemson University who is thinking about entering the field of technical writing and wanted to ask me a few questions. After I recorded the podcast, she was kind enough to transcribe it. I polished up the transcription a bit so that it would be more readable.

How did you make the career transition from academia and teaching to technical writing?

I taught basic writing courses to university students at The American University in Cairo for a couple of years. I also taught composition as a graduate student at Columbia for two years. Teaching writing is okay, but grading student essays was never fun. It was something I really hated. And at times it was okay -- but by and large I felt like I was just justifying Bs and C, having to explain why these essays were poor, how to improve them, and so on. But that wasn't what I wanted to do. I wanted to actually be the writer, not just teach others how to write. So I transitioned into professional writing.

For a while I did copywriting, which was all right, but it didn't make a whole lot of money. And there's a certain truth element that's often missing in the copywriting role. Finally I decided to go into technical writing because it paid better and I thought, well, alright, I'll try it. And it turned out to be a great fit.

Are you happy with your decision to work in technical communication? Why or why not?

By and large I think I'm pretty happy. Technical writing combines my love of writing and technology. I also enjoy working on projects in IT settings with other people engaged in the same work. That aspect of it that can be really rewarding.

It's not entirely satisfying, though. It can be a little boring and can lack a little bit of excitement. I mean, you're not out there saving somebody's life in an emergency room. You're not winning a case for some poor person being evicted. You basically sit at a computer all day writing instructions or figuring out how something works, and you occasionally interact with people. It depends on your role, it depends on the project. Some projects are a lot more fun than others, but by and large it is a good choice and I'm happy with it.

Could you tell me a bit about the first technical writing project you ever worked on? What were a few of the challenges – or successes – you faced when first starting out?

I started my tech writing career at a financial institution and, of course, one of the first applications I documented was a financial application. I remember the senior writer who was training me coming over and telling me that I needed to explain individual steps for printing a document. I was blown away by the level of detail I had to include. I couldn't just assume people could figure things out from a few basic notes (e.g, To print the document, click the Print button). It really had to be detailed instruction (this is something I challenged later).

The other thing she told me is that subject matter experts are somewhat busy and that I needed to save up my questions. That's something I also challenged later -- you can't have that passive, timid mindset all the time. Sure it's good idea to save your questions when you've got a bunch, but never be afraid of approaching somebody for the information you need.

What advice would you give –- if any -– to those looking to start, or transition into, a career in technical writing?

I wrote a post about this, called 7 Steps to Getting a Job in Technical Writing. The first step is to get a degree in something related to technical writing, usually a degree in English with an emphasis in technical writing. If you have a writing degree, great. But you need to ground yourself in the basics so you know what you're doing.

After that, get some real experience doing technical writing, because you're not going to find a job unless you have actual samples of projects you've completed. Learn some of the tools. Put together a portfolio. Start a blog. Move to where the jobs are. And volunteer in the STC.

I elaborated on each of those steps in the post. I'm giving a talk about these points later, on October 8th, and I'll definitely record that. But basically, those are the steps I would suggest. And of course it depends where you are in your career. If you already have a career, the steps to transition into technical writing may be different. My seven steps are intended for students still in the university.

How would you describe your duties on the job? What might a typical day at work for you "look" like?

The typical day thing is hard because days aren't typical. You do a lot of different things at different points in a project. You may go through like a writing phase, a learning phase, a design phase, a configuration phase (especially with context-sensitive help). I don't chunk out my days at one-hour intervals doing all these different things. I get in the mode of doing something and spend half the day on it.

For example, here's how I spent yesterday. First I had to review a handful of presentations for an internal conference. (Sometimes you have to review materials others create.) Then I spent the latter part of the day configuring a relationship table, which is a set of related links for topics. I made sure each page on the user interface had context-sensitive help. I realized that some of the pages I configured weren't the right pages that I wanted to show up in the context-sensitive help, so I had to add some help topics.

I also spent some time troubleshooting a technical glitch. Whenever somebody clicked the help button, it opened a new window, which is what I wanted, but if they didn't close the help window and instead clicked the help button again, a new window appeared on top of the previous window, resulting in multiple help windows. So if they clicked the button five times, they would get five different windows open. I tried to figure out how to fix that. Since I don't really know much JavaScript, it was a little hard. I can code a JavaScript link, but to try to sit there and troubleshoot an advanced JavaScript problem is over my head.

That kind of troubleshooting is typical -- trying to get your help to look right, whether it's troubleshooting something in your help authoring tool or your page layout tool, or whatever -- is common. You can spend a lot of time troubleshooting various problems.

What software programs or other technology do you use on a regular basis?

Tools are always a hot topic, but I have decided on MadCap Flare as my help authoring tool, Adobe InDesign as my page layout tool (which I use for shorter documents), and Snagit for screenshots. When I create video tutorials, I use Camtasia studio. I also work with SharePoint. Sometimes I'll use Photoshop if I'm doing something advanced with graphics. I'll use Visio if I'm trying to illustrate a workflow or something. On my blog I of course use Wordpress. I use most of those tools quite frequently. (I don't have Wordpress at work, but I'm hoping to get an installation going and try to do something there.)

Could you describe a recent challenge you've been presented with at work and how (if possible) you were able to overcome it?

I recently discovered that somebody was planning to send out a guide for working with Joomla to build a country website. The guide was just written by a non-writer, somebody who was more of a coordinator. The guide wasn't very good, and I basically said that. I said, Look, this isn't good. The guide needs to be rewritten. The instructions aren't in numbered steps. A lot of details are missing. It doesn't look very professional. And so of course I ended up having to rewrite it myself, and it took about three weeks. But I felt pretty good about the end result, and I think overall the people using those instructions will be grateful.

It can be a constant challenge to get people in your organization in the mindset that technical writing needs to be done by the technical writing team rather than the project manager or intern. When you have a large organization, it's easy for people to be unaware of your team, unaware of what you do. They don't want to be burdened by your process. They sometimes want to just write it themselves in Microsoft Word and get it done -- and they don't realize that it's terrible. It's a constant challenge trying to get people in the mindset that the documentation -- the manuals, the instruction, the video tutorials, quick reference guides -- need to be done by the tech comm department.

What is one of your favorite success stories from working in technical communication? Anything substantial or particularly rewarding that you've been able to work on thus far?

I think the way you determine whether something is successful is if you release an application and it takes off. You may just be the technical writer on a team, but you're also contributing other things. You're contributing towards usability, you're interfacing with customers, you're making sure that things work right. You're part of an entire team that is building and producing software. If the software is successful, you're part of that success. We had an internal application at my work that was really successful and it did take off and lots of people started to use it. If you're not bombarded with a bunch of questions by users, if they're able to search and find the answers and learn for themselves, that's also a success.

Do you pursue any continuing education opportunities – either required or optional – for your job? If so, what type(s)?

I do try to keep up with blogs, articles, conferences, and other types of published information. I definitely try and keep up. But official courses? No. There's a sense of distrust that a lot of people in the industry have about people in the academia. Whether academics are out of touch or not, I don't know. I've seen studies debunking that myth. I've also heard academics say they feel out of touch with the current issues in the workplace. So going back to the university to learn how to improve in the workplace isn't always an idea that's appealing.

How do you feel that your education did – or perhaps did not – prepare you for your current job? Are there any courses you wish you would have taken or skills that you should have mastered but didn't? Any regrets?

I have a degree in English and a degree in creative writing. The second one is a Masters degree, the first a Bachelors. Neither prepares you a whole lot in terms of what you're going to do. You could say that the analytical abilities to assess and comprehend larger structures of text and manipulate them is helpful to you as you organize help topics in a large project. So sure, there's crossover. In an English degree, you definitely learn grammar and how to write. In fact, just having the love of writing is helpful. But really, as a technical writer, you're not writing essays, you're not doing creative writing. You're not doing literary analysis.

Are these activities truly helpful in preparing you for technical instructions? A little. You need a basic command of the language and good common sense. But if I were doing it again, I would have probably double-majored in English and graphic design or computer science.

Approximately how much of your time is spent traveling – whether for your job or for other professional opportunities?

Zero. I'll sometimes go to a conference, but that's an exception. I don't know many technical writers who have huge traveling burdens -- unless you're a contract technical writer and you're traveling between sites.

Do you focus any of your time and/or career goals on publishing, presenting, and or attending/speaking at seminars, conventions, and other outlets?
I publish a lot on my blog. And through that I often get invited to speak. I've given quite a few presentations (quite a few for me, anyway). And I really like my blog. I feel like I haven't posted much lately, but it does keep me engaged, it makes the work fun, and I can't imagine what my career would be like if I didn't a blog. It gives me an outlet for expressing what I'm experimenting with and reading.

How has the work on your blog and podcasting helped – or hindered – your personal and professional interests?

My blog has never hindered my professional growth (unless I stay up late spending too much time on a post). But really, having a blog helps me because it forces me to keep up with the latest news and trends. It gives me an outlet for my creative expression, which is important for me because I like to write, and I don't always get the opportunity to itch that creative drive at work. The blog is an outlet for that. It keeps me creatively satisfied and also focused on the career.

My podcast is especially helpful to me in getting to know other people in the field and interacting and learning from them, so it's fun. It makes it a lot more engaging. It also helps brand me as an expert, which helps position me for jobs if I'm looking. My wife is also a blogger, so it's an activity we do together.

Does your blog at all affect your relationships with your co-workers and supervisors?

Sure. I mean, I imagine a little bit. There's an increase in communication. Two of my colleagues are also bloggers: and We are also engaged in the STC together, so it makes it a little more fun. There's more camaraderie, more interaction, and more passion behind what we're doing.

What is your definition of "technical writing"?

One definition I've heard is that technical writers help non-technical people understand technical things, which is partly true unless your audience is technical. In that case, you're helping technical people understand technical things.

My dad tends to think of me every time he reads poor instructions, so in the general public eye, technical writers write instructions to help people learn how to use software, gadgets, or other technical things. That's pretty much how I see myself and the profession: helping people understand and learn how to use all the technology that's coming out. We live in an age where there are new web apps and other software developed daily. Somebody has to help people learn to use the new technology. That's how I see my role as a technical writer: helping people learn new technologies.

What changes have you seen occur in the field over the past five years –- and perhaps what are your projections, if any, for the field for the next five years?

There's been an emergence of DITA (Darwin Information Typing Architecture). DITA is an XML structure that you apply to your writing, which if you do, you can then transform it into PDF, HTML, and other formats using something called the DITA Open Toolkit. This allows you to single source your material. DITA is a huge buzzword. I'm not really into DITA since I don't have a huge use for it in my work, but a lot of people do and they're really excited about it.

I do single source, when I have that requirement -- and I can do that all through MadCap Flare. MadCap Flare now publishes in DITA, so that gives you more possibilities. One project I would really like to try, speaking of DITA, is to author content in Flare, export it as DITA, and then import the DITA topics into WordPress and see if I can make like a website-looking help file. But I'm still working on that.

Another trend I've seen is the de-standardization of help authoring tools. RoboHelp is no longer the main online help tool. There is really no single tool. There are several major players -- RoboHelp is one of the players, and Flare and Author-it and maybe even Doc-To-Help -- but really, there's no single tool -- it just depends where you are.

I've seen people grow less and less patient with long manuals. I don't think people want long manuals anymore. People expect to learn by playing around with the application, and maybe reading a help file when you need it. I don't know if it's always been that way, but I definitely don't see much emphasis on long manuals anymore.

As far as where the field is going, I see more talk about wikis. But whether a wiki would work for you is very project specific. Unless you're working in an open source or community environment and have a lot of contributors from people in different locations, or unless you have just an environment where tons of people want to contribute, I don't see wikis as taking off. But wikis definitely have an appeal. We use social media within our team. We use Twitter, we have a team blog, and we also have a team wiki. The tools are excellent tools for collaboration. Whether they're going to make the help documentation space take off is another question.

As far as trends into the future, I tend to emphasize video tutorials and quick reference guides as the main products I produce, rather than reference manuals. Even if you can single source a reference manual for five different audiences, to me it's still a manual. In my experience, people like short formats and they like videos. So those are two formats I'm pushing. But at the same time, I still write the online help, and if you write it in a help authoring tool, you can single source it into a printed output. So really I produce all of the main deliverables: the online help, the printed reference guide, the quick reference guide, the video tutorial.

As far as other trends, I don't know. Some people talk about round-tripping from DITA to wiki and back and so forth, but I don't think that's common.

Which three skills do you believe are the most important in order to find success as a technical writer?

The ability to write is key. If you can't write, it's like being a football player with a poor ankle. It's going to nag you and bring you down.
Another key skill is having a technical ability. If you can figure out how things work, figure out how to learn new software applications, that's key, because most of your job involves that. You have to figure out both what you're documenting as well as the tools you're using to write and publish those instructions.

Finally, having some people interaction skills is also useful. Your ability to interact with project managers, quality assurance engineers, developers, and other people on your team is highly important. I don't know how you develop those skills, but definitely don't neglect them.

With regard to a recent post by David Farbey that you linked to on your blog, what are your thoughts on calling yourself a "technical writer" versus a "technical communicator" Does one better describe the job over another –- and do you believe that the industry is shifting one way or another? If you had to pick -– either from one of these two, or from something else -- which title would you choose?

I've always hated the term "technical communicator." It's an attempt to encompass all the various tasks we do, from illustration to videos to training -- everything. But really, it fails. Communicate is a verb you use when you're trying to talk to an animal or something. You "communicate" with an ape. Or you would use the verb "communicate" if you've finally managed to communicate an idea to a mute. Or if you're hurt and stuck on an island and see a plane flying by, you light a fire or shoot a flare gun to communicate that you need help. It just doesn't seem like the right verb for our profession, in my opinion. I think that "technical writer" is fine.

And that's how all the jobs are listed. People don't search for "technical communicator." If you search for "technical writer," you find tons of jobs. But if you search for "technical communicator," you hardly find anything. Some people are rabid about this and they hate the word "technical writer" -- but "technical communicator" is really no better. And the bulk of what I do involves written words, so I'm fine with the word writer. I've addressed this topic in a previous post, by the way, so I can refer to you to more if you want.

What role does STC membership play in your career – and what do you feel are the biggest benefits of joining?

This is another controversial point, but part of the reason I'm involved in the STC is because my colleagues are, so I think it helps build relationships at work. Plus, it's fun to network and interact with other professionals in your area. I feel that's the major benefit. You could join STC for whatever you want -- whether you just want the magazines and the journals and so forth -- but, honestly, there's great information on blogs and online. For example, try the TC eServer Library for starters. There's tons of great articles that Geoffrey Sauer organized and archived. So you don't really need the Intercom and the Tech Comm journal.

But the ability to find out who's in your area, who the other professionals are, and develop relationships with them is valuable, and it gives you more of a community. I mean, what's the value in a community? That would be the question to answer if you're trying to ask what the value of the STC is. Inasmuch as a community of tech writers is valuable to you, the STC would be valuable. And most employers will pay for your membership as well.

Do you belong to any other organizations or participate any additional social networking – other than the work you do with your blog and the STC?

Not really. I'm on the Content Wrangler Community and LinkedIn groups, tech writer listservs, but I don't really participate much. I'm pretty much overwhelmed with the information already coming in. If I'm looking for something specific, I may go into those groups. But not really.

Personally, I think these other forms -- Twitter, Facebook, LinkedIn -- have their place, but the blog is where the heart of everything that is interesting happens. Twitter is a 140-character little message that could just some little quirky thought you have. In contrast, a blog post is something you think out, something you write out, revise, and polish. Good writing can actually change the way you think. After you write an essay you may see the world differently. After I Twitter something, that rarely happens.

And Facebook? I actually don't really use it, I just syndicate my Tweets and blog posts through Facebook. I'm sure Facebook can be a great way of keeping up with friends if that's what works for you. And LinkedIn? I've never seen the appeal. I get tons of invitations to join people's LinkedIn networks, but I've never seen anything come out of that other than people looking cool because they have 600 connections.

I really recommend the blog route -- but then again, it's not for everybody. Some people don't have time, which really means you just want to dedicate your time to other things, which is understandable. I'm kind of in that mindset right now. I have a lot of things to do and the blog cannot be the very top one. Just providing for your family is right up there. And people who have multiple jobs may not have a lot of time to keep a constantly updated blog in a way that is going to fulfill them.

What are your thoughts on available tools such as Facebook and Twitter for professional marketing and/or networking?

Like I said, sure Facebook and Twitter are great for just keeping up with others and, yes, it should be part of your professional marketing and branding strategy. But if you really want to brand yourself as an expert, start a blog and let your posts focus on what you want to brand yourself as. Writing 100 posts on something will get you a lot more mileage than posting 100 Tweets or trying to interact with people on Facebook.

I've droned on for quite a while and I've answered all of your questions. I hope that was helpful to you and to anybody else thinking about a career in technical communication.

Just as a closing thought. I really do think that technical writing is a hot field because technology itself is such a hot field. As long as there is a strong technical drive with new applications and IT companies, new websites and interactive applications with web services, and so much forward-technology motion, then you're going to have a strong need for technical writers to explain how this works to people. It's sad reality that tech comm. is one of the more neglected aspects of the technical revolution, that people tend to leave behind those who aren't so tech savvy. That's lamentable, because the more people you have on board, the more powerful your application becomes.

And so the technical writer's role is actually hugely important. Knowing and feeling that does give more validity to my job, it gives more purpose. I do love what I do and I would never change it. I knew that the first few months after I went into technical writing, I knew that was where I wanted to be. There's a lot of room for improvement in the field. There's a lot of room for creativity -- not so much in the way you write, but in what you do with your technical delivery, how you design and lay out your help, how you arrange and organize your content. These tasks rely on a lot of creativity. How you problem solve is probably the biggest aspect of my job -- problem-solving, all day long. That in itself is really rewarding.

I really encourage you, especially if you're an English major, to check out technical writing. It's not boring. It's not a last resort, it's not a sell-out. It can be something that: financially sustains you, engages you intellectually, and is just a fun environment to work in.

Check out the other posts on my blog, I have a lot of other podcasts there. If you have feedback, I would love to hear it.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.