How to Write Editing Comments For Authors 

I spent some time as a technical editor for the US Army. I was responsible for editing very technical materials produced by engineers, scientists and technicians doing some very technical research. I learned quickly that one of the most valuable assets an editor has is the ability to “talk” to authors through comments. I want to talk about some of the things technical editors can do to make better comments using MS Word’s commenting feature.

Past research has suggested that comments—inserted directly into a document—are the second best thing when compared to face-to-face discussions between editors and authors. Because you can insert a comment right at the spot you want to talk about, an author gains context for the comment. It’s almost as if you point a finger at a spot and say, “right here…”

I always urge my technical editing students to insert as many comments as they can when editing. But what kind of comments should you insert? There are a few different kinds I try to write when editing someone’s work. The example below does a couple of things. First, it tells the author that I don’t understand the sentence or the meaning they were trying to relay. Second, it gives the author a suggestion for improving the sentence depending on what they were trying to say. Doing this is so important because it tells the author that you aren’t simply going to change the text without cause. It also helps the author by suggesting how to improve the sentence. Often authors will just go with my suggestion and be thankful for the extra effort.

The next comment (below) is perhaps one of the most important to include. This comment is simply telling the author to ensure the meaning of the sentence is still the same. I do this often, mainly because studies have found that one of the biggest complaints authors give about editors is that they change the meaning of the text through their emendations. To ward against this I tell authors, “hey, I made a bunch of changes here, check it to be sure.”

A last type of comment to include often, especially when you just begin working with an author, is one telling the author why you made a change. Another big complaint authors have is that editors make arbitrary changes just for stylistic or personal reasons (you just think your way sounds better). This ticks authors off to no end. So, if I don’t know an author very well I’ll include comments all over the place—especially in areas with lots of changes—to cite why I’m making a change to their text. As I grow to know the author, and they trust me more, I’ll taper off on the amount of these I include.

For technical, professional and business communication help in the Las Cruces, NM area, visit Lanier Infomedia. 

Last update: 27-03-2009 13:37

Using Comic Books for Technical Instruction 

It's one of those amusing facts: when you tell someone you're a technical writer, you explain it by saying that you write "instructions." This is often the view people have of what technical writers do. Of course this view is completely inaccurate because technical writers create all kinds of documents and information pieces, not just instructions. But even so, instruction writing--especially for the software industry--remains one of the biggest concentrations within technical writing. However, writing instructions--dull as it may seem--can be interesting and fun, especially when you approach it as Google did when they created the documentation for their new web browser, Chrome.

Google has always been a bit quirky. From their logo to the names of their products (Sketchup), they take a sideways approach to what they do. So it really isn't that surprising to me that the end-user documentation for Chrome is a comic book.

Using comic books to dispel technical information is certainly not new. The US Army for example has been using comic books for years to relay important instructions to its troops. The picture below is from a comic book made in the 1960's that tells soldiers how to care for and clean their M-16 rifle.

Using comic books for technical instructions may seem odd, but there are actually some very good reasons why this approach is sensible. First, comic books allow the writers to employ a character to tell the reader how something works. Therefore, it is more conversational and more like learning from a tutor or instructor than a linearly structured set of instructions.

Obviously the graphic and text can be more dynamic and interesting in what would otherwise be bland information. Though the graphics are cartoon-like, that is what makes them so appealing to a wide variety of readers.

It also allows more abstract concepts to be explained more easily. In Google's case the concept is the mechanism of the Chrome web browser. The character "tells" you how the web works in general, and then "tells" you how Chrome is different than other web browsers.

Another aspect about using comic books for technical instruction is that it can be appealing to a younger or less educated audience. This point was not lost on the Army, and is probably the principle reason they used comic books to tell young soldiers how to properly handle their weapons.

The above point also makes comic books ideal to be used for a broader audience. In technical writing one of the unwritten rules is to write for the lowest common denominator--the person who is the least educated or knowledgeable in the subject. This strategy allows you to hit more readers than otherwise, and it saves you time from writing a different document for each set of readers.

There are drawbacks of course. One in particular is that comic books are fairly cultural, and not every culture will recognize their usefulness (or lack of usefulness). They may be perceived as childish or silly by some, and run a risk of not being taken seriously. In all, though, they present a great way to do something different when writing instructions.

For technical, professional and business communication help in the Las Cruces, NM area, visit Lanier Infomedia. 

Last update: 27-03-2009 13:37

What is a Technical Writing Portfolio?

This is another of those questions students and young professionals often ask me. Simply put, a technical writing portfolio is a collection of past work in technical writing.

The next natural question is, "Do I need one?"

YES! YOU DO!!!

As I've stated many times before, and as I firmly believe, technical writing, indeed all of technical communication (graphic design, technical editing, the whole of it), is an applied discipline. In other words, technical writers don't just sit around and theorize about ideas, they make things. As such, technical writing is more like engineering or architecture and less like disciplines in the arts and sciences, such as biology or literature.

For simple proof just look at two of the strongest academic programs in technical writing in the country: the University of Washington where the technical writing program is housed in engineering, and Texas Tech, a huge tech school that houses the largest technical writing program in the US.

So, because it is an applied discipline, employers expect technical writers to show proof of their application. Engineers can point to specific objects they've helped to create: circuits, bridges, cars, etc. For technical writers, they are expected to show examples of things they've written or helped to write: award-winning grant proposals, end-user documentation, websites, etc. Examples of things you've created are the best and most conclusive way to demonstrate to a potential employer that you have specific experience in technical writing. A technical writing portfolio is simply a collection of these examples.

"So how do I make a portfolio?"

I see portfolios typically take a couple of forms. The first is the standard, hard-copy collection of samples, and the second is an e-portfolio.

The standard, hard-copy portfolio can just consist of a 3-ring binder holding your collection of work. Put each document into clear plastic sleeves with blank, tabbed sheets to separate each one. If the document is really long, you'd be best served to only select a few of the pages most emblematic of your work (try those that represent work you alone completed without help from collaborators).

Try to include a variety of different types of pieces made for various employers, reasons and with a different types of tools. Personally, I have about 7-8 different pieces that represent internal documentation, external user documentation, external non-technical documentation (white papers), and web-based work.

Along with each piece I inserted I wrote down what would be significant to an employer about each piece. Some took extensive (meaning more than usual) research, each took knowledge of important technology to create (like programming languages or software tools), and each took a combination of skills (like writing and graphic design). So along with the samples of work was a narrative about how that work was created and the factors that would make me appealing as a technical writer. Not every employer will read these narratives, more than anything they are for me to arrange my own thoughts on the significance of the samples I've included.

E-portfolios are essentially a web-based version of the 3-ring binder. What's nice about creating e-portfolios is that it gives you the option to dazzle a bit with things like Flash or other multimedia. It also allows you to include longer items. So instead of just choosing a few pages from a document, you can include the whole thing as a PDF file. You can host an e-portfolio on a CD or, perhaps better, on a website.

Either of these is an appropriate choice, but I think they can be used for different reasons. The binder you would take to an interview with you, while the web-hosted e-portfolio can be pointed to from your resume and an employer may scan it before you're ever contacted.

Of course, this is assuming that an employer doesn't just simply ask for you to email a few pieces with your resume, or shortly after submitting your resume. If this is the case, the portfolio is still a good idea, because it keeps you from having to dig through your files to find samples and instead keeps them organized and at your fingertips.

For technical, professional and business communication help in the Las Cruces, NM area, visit Lanier Infomedia. 

Last update: 27-03-2009 13:38

How to Gain Experience in Technical Writing 

This is another one of those questions I'm asked all the time by both students and young professionals starting out. In any industry its hard to break in, but in technical writing much of the hiring process is based around your past experience. After all, technical writing is an applied discipline, so employers have every right to see how you've applied it before working for them.

If someone is looking to eventually get into a full time position somewhere, but will settle for something less permanent for the time being, I usually recommend trying a contracting company, like Manpower or Volt or similar organizations. While the duration of work is typically short--anywhere from 3 months to a year--the experience gained is great. And technical writers can often use contracting experience as a springboard into something full-time.

If you only have a short period of time to get some experience--say you're graduating soon or the like--then you'll want to perform writing jobs (as many as you can) free of charge. Much like attorneys perform pro bono casework when starting out to pad their case history, technical writers can work gratis for many deserving customers to perform real professional writing, get great experience, and start collecting samples for their portfolio.

Who you work for will depend on what type of writing you want to do. If you are looking to be a professional grant writer, then you'll have tons of small non-profit, social service organizations asking for your free help. Finding them is simple enough: cold call from the organizations you find in the phone book. There's nothing to be embarrassed about, after all you're volunteering your time and talents to help them out. Try church organizations, groups that help troubled women or children, the needy and homeless, etc. Not only will they love to have a grant writer, they'll probably also have a lot of other business correspondence as well, so if you're not looking to do grant writing you can still find some good experience in places like this.

If you're thinking about going into the software industry, there's nothing better than getting involved with an open-source software project. These projects are usually chock full of programmers, but thin on the writing staff. Chances are they'd welcome someone to take over their documentation tasks, from user manuals and install guides to API docs and help files. You can search www.sourceforge.net to find projects that need help. Then simply contact the person listed and offer your services. From there, it becomes a real-world learning process that pays off with great examples of work for you.

Generally speaking, once the word gets out that you're doing free work, people will be sending you emails and calling you all the time: you'll probably have to tell a lot of people know. But taking advantage of all the free writing work out there will pay off with a portfolio padded with real examples of real work.

For technical, professional and business communication help in the Las Cruces, NM area, visit Lanier Infomedia. 

Last update: 27-03-2009 13:38