May 2008 | HelpScribe

Technical writing reviews made easy

The review process is essential for producing accurate documentation. Great technical writing must be both accurate and well written, and there's no better way to ensure your documentation meets these requirements than submitting it to SMEs and other writers for review.

Here are a few tips to ensure that you get meaningful comments from your reviewers.

Ask direct questions

Often the best way to get feedback on a particular section of content is to embed a note to reviewers. For example, if you aren't sure about the order of steps in a procedure and cannot verify that order personally, you can embed a note to reviewers asking them to verify the order. Such questions allow you to make optimal use of each reviewer's time. Unlike phone calls, email messages, or personal visits, a scheduled review allows you to present such questions in a non-intrusive manner, and is less likely to be seen as an interruption.

Such questions should always be highlighted in your documentation reviews, along with a note instructing reviewers on the exact question you need answered.

Limit reviews to new or revised material

To make reviews more productive, avoid including material that hasn't changed. That way reviewers can focus on the content that needs the most work.

There will be times when all material should be included. For example, if a major overhaul of the product has taken place. In such cases even older content could be questionable and should be reviewed by those that know the details of the changes.

Set a clear deadline

Reviews of technical documents should end at a pre-scheduled time. That way you can begin to incorporate review comments without worrying about receiving conflicting edits at a later time. The due date should be made clear at the start of the review, and should appear in writing on the review copies or in the email message to reviewers.

If a reviewer cannot return comments by the scheduled date, simply schedule a second review. If this isn't possible due to deadlines, try to give the reviewer a few extra days to complete their review. Avoid incorporating changes before all reviews are received unless you absolutely must. Late edits could make any work you do obsolete.

Provide electronic copies

Printed review copies are great for later reference. However, it takes time to deliver copies, especially if you work on documentation that must be reviewed by people in different locations. This is especially true for companies where employees work remotely or telecommute.

To facilitate the review process, try to provide a PDF of the review document. That way all reviewers can access the PDF immediately and print a review copy. You may also wish to allow electronic edits. In such cases you could provide a copy of the actual source file (Word, FrameMaker, etc.) assuming reviewers have the software necessary to make edits electronically. If you choose this option, be sure to make good use of change tracking features. Electronic reviews allow you to share information faster, and they save paper.

Double check your reviewer list

Be sure to include the right people in your review. In addition to SMEs, you may need to include representatives from Support, Customer Service, or other departments based on the type of information that appears in your document. Include only those you need to get a full and accurate review. Too many reviewers might slow the process down. However, some content, such as system requirements, will require a larger number of reviewers to ensure accuracy.

Following these guidelines will help ensure that your content is accurate and clearly presented. The trick to reviews is balancing your need for feedback with appropriate project management. Reviews can be frustrating if you let them get out of hand. Help your reviewers give you the information you need and your users will end up with better documentation.

The power of Perl

For most technical writers, writing code was never part of our job description. Often programming skills aren't relevant enough to our jobs to justify the investment. However, a bit of Perl knowledge can go a long way, especially if you spend a great deal of time converting documents across formats, or automating your documentation process.

The power of the Perl language (at least for writers) is its ability to handle regular expressions. You can perform some crazy wildcard searches. For example, if you need to find all instances of <p class=[whatever]> and replace it with <p>, and then wrap the entire file in updated template code, Perl is the tool for the job.

Add a simple loop to the code, and you can process a thousand HTML files in seconds.

"But can't I just do a global search and replace from my HTML editor?" No, not exactly. The real benefit of Perl is that you can combine multiple search and replace options into a single script. That script ensures that the same operations are performed every time. There is no room for error. The benefits are much like those offered by the industrial revolution; the process is completely automated and your results are more consistent.

You could make a huge checklist and tediously search and replace until you caught everything.

Or you could write a single script to do the job, and pass that script to other writers. The combined benefits are huge. These "batch" operations can seriously boost your team's productivity, especially for very large projects.

Perl isn't the easiest language to learn. In fact, the regular expression syntax is a bit mind boggling at first. However, you only need to learn a little bit of the language to seriously automate tedious technical writing tasks.

If you are thinking about adding some programming skills to your resume, Perl is a great place to start.

Does the thought of freelancing scare you?

Photo: channah

What writer hasn't dreamed of working from their back porch on a sunny day, with a laptop and a cold drink?

Aside from the ability to work in your pajamas, as a freelancer you can set your own rate of pay, choose which projects to spend your time on, and make your own rules.

But there's a dark side to freelance writing that keeps many of us from jumping ship. The great "unknown" is waiting for us, like the dark spots in deep water; we can't see the bottom.

If you're like me, you've probably thought about freelancing often. And every time, such thoughts lead to concerns about...

Money

Will you make enough to survive?

While freelance rates sound promising compared to a 9 to 5 job, who can say whether the market will sustain you? There's a reason most consultants advise putting away six months worth of emergency savings. Sometimes the work just doesn't come.

New skills

If you're an introvert, do you have what it takes to call clients and promote your services?

Are you ready to meet new people, get to know their business goals, and sell them on your ability to help meet those goals?

Can you ask someone who owes you money to pay up?

Freelancing requires a whole new set of communication skills. The only way to land work is to sell your services effectively.

Hard work

If you freelance, the days of waiting around for the next project are gone. Instead, you'll struggle to keep up, since freelance writing requires you to handle managing the books, administrative tasks, sales, and customer service. Also, when a project goes bad, the responsibility to fix it lies squarely on your shoulders.

And yet...

I still find myself dreaming of working from my back porch, lemonade and laptop in hand.

The great "unknown" still makes me nervous. But I imagine those unknown factors will shake out soon enough for anyone who jumps in to test the waters. Plus, there's always the option of tiptoeing in, one freelance writing job at a time.

And if you take the plunge, maybe you'll find that your entrepreneurial spirit is perfectly suited for swimming those dark waters. Maybe you'll make way more money than you are now, and actually enjoy meeting new people and running the show.

So, does the thought of freelancing scare you?

How a technical writing certificate can boost your career

Technical writing certification has been a touchy subject in communities devoted to the field. Many discussions have revolved around how a certification process might add unnecessary bureaucracy, or how challenging it would be to set fair requirements for such certification.

However, for the individual, the benefits of certification are hard to ignore. Here are some ways that a technical writing certificate can boost your career.

By enhancing your reputation. Earning a certificate keeps you involved, and being involved is a great way to turn your name into a brand. People like Tony Self, Joe Welinske, and JoAnn Hackos have built reputations in the technical writing community that have allowed them to succeed in related industries such as consulting, training, and publishing; all great ways to make money and leverage technical writing skills.
By building your network. I've heard many STC critics say things like, "Why would I want to waste time hanging around my competition?" That's absurd. Why do future business leaders attend schools like Harvard and Wharton? Because they build networks of peers that will open doors in the future and offer support and advice during hard times. Other writers who are paying cash and working hard to earn a technical writing certificate have the ambition to become future leaders. Get to know them now. They could become future business partners or hiring managers.
By providing exposure to the daily realities of a technical writing career. Universities are aimed at providing a well rounded education and a solid grounding in theory. Technical writing certificate programs, on the other hand, are focused on developing a more targeted set of skills that will allow you to be productive immediately. While other new graduates are learning the ropes, you'll be able to hit the ground running.
By revealing gaps in your existing skill set and filling them. If you've been working in the same job for a while, chances are you are repeatedly using the same skills, while others are fading from neglect. A certification process made up of technical writing courses or seminars could help you brush up on technical writing skills that you haven't had a chance to use in your daily projects at work. Many online technical writing programs offer certification or advanced degrees to help you further your career.
By helping you compete with others who are already certified. Failure to do so could cost you at your next job interview or contract opportunity.
By increasing the size of your paycheck. Certification increases your value as an employee, and can be used to argue for a higher salary. If you are a consultant, you can use your certification to justify higher rates.
By providing proof of expertise. Certification, much like an advanced degree, can give you the necessary clout to act as an expert speaker in your field. It can help build trust in the minds of others.
By adding clout to your resume. This is especially beneficial to those transitioning to technical writing from other fields, or recent graduates who have little work experience. A technical writing certificate can make a sparse resume look more promising.