August 2010 | HelpScribe

Technical writing and efficiency

Writing technical documents is a complicated process. Even more so if you work in a large department, producing many documents for multiple products. Working efficiently is important if you want to stay on top of deadlines and avoid pulling your hair out over unnecessary complications.

However, sometimes process improvements are a double-edged sword. While a change in your process might make one aspect of your workflow more efficient, it can often increase the workload in a different area.

Let's say you have several projects in process, and you devise a system for tracking status and metadata about those projects using a fancy Excel spreadsheet. As long as you keep the information in the spreadsheet up-to-date, it is useful and helps you stay on track for hitting deadlines.

But what if you slip and forget to update the spreadsheet? And what if the amount of information you are recording in the spreadsheet becomes tedious to keep up-to-date during a last-minute rush to meet a deadline? In technical writing, a lot can happen during the few days prior to a product release.

Unfortunately, the work necessary to maintain any system can offset the efficiency and peace of mind you gain from that system.

So, before you implement a complicated system for improving your workflow, ask yourself: "Is this really going to make my job easier? Or is it just adding to my workload?"

If you sense that it will increase your workload, don't just ditch the idea completely. Instead, ask yourself if you can reap the same benefits in another way. Perhaps you can come up with a different process that requires less maintenance.

For example, instead of using a complicated spreadsheet for tracking project details, perhaps you can embed such metadata into the documents themselves as hidden text. You're going to be working in those files regularly anyway, so the risk of failing to update that information is greatly reduced. Then you can run a macro or script to pull that data into an on-the-fly report any time you want. The need to maintain an external spreadsheet disappears, and you can still track the details that are important to you.

So the next time you try to make a process more efficient, be sure to consider the cost of maintaining that process. You want to spend your time writing manuals, not stressing out over a system that doesn't work.

Increase your income

Part of the reason many of us become technical writers is because it offers high rates of pay compared to other writing jobs. Here are a few ideas for maximizing the financial rewards of your technical writing career.

Be the expert. Ask yourself what struggles your organization will face in the near future and over the long term. Use some free time to build your expertise in those areas so that you can be a major contributor. By guiding your team through such struggles, you drastically increase your value.
Consider a promotion. If your company offers upward mobility within your department, think carefully about whether you would want to take the job, and start preparing now. Write down a list of the skills and responsibilities such a promotion would require, and start proving your worthiness. If you aren't sure about the availability of promotion, or the responsibilities, ask your manager or HR staff. (Tread carefully though, so you aren't perceived as a threat to your superiors. Hopefully you aren't in such a dog-eat-dog environment, but it's worth mentioning.)
If your current position offers no hope for upward mobility, consider looking for positions that do. If you don't seek, you won't find. Look for companies that offer upward mobility and are a good match for your skills.
Further your education. While you don't want to be perceived as overqualified, statistics show that higher education correlates to higher income. Consider whether certification, an advanced degree, or a related degree such as computer science or engineering would increase your value; many online technical writing programs are available.
Volunteer for challenging assignments. Some roles are simply more challenging than others, and may require greater responsibility and more overtime. However, the rewards usually follow suit.
Consider freelancing. Building your own technical writing business can be difficult, but it can also be highly rewarding. In addition to working your own hours, you get the benefit of setting your own rates. Many freelancers start out doing side jobs in their free time until they build up a stable client base.
Write a book. The publishing industry is always looking for authors who are experts in cutting-edge technology. Authors usually receive an advance as well as royalties from book sales. Publishing is a great way to increase your income and build your reputation at the same time, and establishing yourself as an expert can lead to future offers and profitability.
Get involved in web publishing. Your ability to write content and deal with technical issues makes you a perfect candidate for running a blog or website. Such a site can help you build your reputation, land new contracts, and generate income from advertising, affiliate offers, or products that you create yourself.
Leverage social media as a networking tool. Connect with others on LinkedIn, Twitter, and other sites and build your reputation by contributing regularly. Doing so will help you stay informed about interesting projects, lucrative opportunities, and open positions that may not be posted elsewhere. As they say, it's not what you know, it's who you know. (Actually, I'd say it's about 50 / 50; this industry seems especially appreciative of knowledge.)

Hopefully these tips are helpful in maximizing your technical writing income.

How technical writing committees keep things moving

How many times have you seen great ideas fall through the cracks as higher priorities steal your team's attention? Technical writing teams have to juggle a lot of priorities, and sometimes we have to sacrifice improving our process in order to hit deadlines. However, letting those great ideas slip away permenantly can be a big mistake over the long run.

That's why committees are so great.

Committees allow managers to delegate tasks, such as research or testing, to a small group of writers. Those writers can schedule regular meetings, draft goals, and ensure that progress is made in spite of the day to day work that eats up most of our time and attention. The committee can then report findings back to the rest of the team.

The effectiveness of technical writing committees depends on a few key factors.

Deciding which long-term goals are worthy of a committee. Especially for small teams, prioritization is essential.
Choosing the right team members for the committee. Project management skills will be necessary to keep the committee on track, and domain expertise is essential for making educated decisions. A balance of personalities and skills is essential.
Establishing a process for tracking decisions and findings, and sharing that information with the rest of the team.
Assigning and tracking To Do items for committee members.
Choosing a chairperson to schedule future meetings and keep things moving.

I've recently been involved on multiple committees and have found them to be very effective. Usually such work grinds to a halt when deadlines loom. However, having a regular committee meeting allows for steady progress and decision making in spite of a busy workload.

So, does your team have a bunch of goals that you can never find time to pursue? Perhaps you need to form some committees.

Turning document reviews around quickly

Hitting deadlines can be a real hassle when document reviews don't go as planned. Here are some tips for getting reviewers to provide feedback efficiently.

Provide a documentation schedule, so that reviewers can agree to review deadlines beforehand. This gives reviewers a chance to warn you if they are going to be on vacation or otherwise unavailable. You can then adjust the schedule or ask if someone else can review the document instead.
Make the due date clear so that reviewers know how much time they have to return comments. Put the date in bold print on your signoff slip and review email message.
Use a signoff slip. Make it look official so reviewers will feel more pressured to comply with your review request and sign off.
Try to keep your list of required reviewers short. One key SME from each relevant department is good. If others ask to be added to the reviewer list, ask if they can be considered FYI (comments appreciated, but not required). Too many reviewers will make hitting your deadline impossible.
For multiple reviewers on the same team, ask them to share a review copy. That way you won't have to sort out conflicting edits. They'll be able to see what other reviewers have suggested and sort out conflicts themselves.
Exclude any documentation that hasn't changed from the review. That way reviewers can focus on the content that needs the most attention.
If you must include all content, provide reviewers with a list of sections that have changed significantly.
Clearly indicate any questions that you have for the reviewers so you don't have to waste time following up later. Either embed and highlight your questions, or put them in a separate cover sheet in the review PDF or hardcopy.
If the review deadline passes and you still haven't received signoff from everyone, send out a follow-up message immediately.
If a reviewer doesn't respond to your follow-up email, send a message to their manager politely stating that you can't reach the reviewer and asking if someone else is available. (Careful, you want to keep things moving, but do this in a way that doesn't tick off the manager or the reviewer. Use your powers of rhetoric, your best Bill Clinton smile, and have some fresh-baked brownies ready.)
If a key reviewer is having genuine time constraints, follow up with the product manager about how strict your deadline is. If they've worked a few days worth of padding into that deadline, they might agree to let it slip if the reviewer is known for providing great feedback.
Use your phone if comments aren't clear. Or, crawl out of your hermit hole and go talk to the reviewer in person. The exercise and social contact will do you some good. Waiting for an email response can waste valuable time if you're trying to hit a deadline.
Some reviewers may request multiple reviews to verify that you have made the correct changes. That's fine if the schedule allows for it, but try to limit it to no more than two reviews.

Remember, technical writing is 50% project management, 40% politics, and 30% writing. (And 0% math, fortunately.) Anyway, try to stay on top of things and your reviews will be less stressful for everyone.

Related post: Technical writing and efficiency

Major documentation mistakes | Are you making them?

Do you want to leave your users feeling confused and frustrated? Writing great documentation can be an uphill battle if you aren't aware of the pitfalls. Success depends on teaching the many skills consumers need to develop to become adept users of your products. Here are some common mistakes to avoid when writing your documents.

System based documentation

Be wary of documenting product features instead of tasks. Your users don't want to know to function of each component of your product. Instead, they need to know how to use these many components to complete actual tasks.

Often system based documentation is the result of engineers and developers providing content. Their job is to build features into the product, so it is only natural that they would write details about individual features. It is your job to take these detailed specs and incorporate them into procedures based on the tasks users need to perform with the product.

Lack of context

All procedures in your user guide should begin with a description of any prerequisite steps necessary for completing the procedure. For example, telling a user to click a button on a dialog is useless if they cannot find the dialog. You can use cross referencing if necessary to point them to any prerequisite instructions, but make sure the user has sufficient context necessary to successfully complete the task.

Poorly balanced content

Consumers will not all have the same goals when they read your user guide. Some will read the guide from front to back to develop detailed product knowledge before they start using the product. Others will use the guide as a reference tool, reading only the sections that they don't understand through intuition. You need to write with various types of readers in mind.

Be sure to include overview information and best practices for users who want to become experts. Also include reference information and granular content for users who are trying to troubleshoot a specific issue, or complete a single task. Try not to make assumptions about your audience; instead, base your content decisions on usability studies, personas, and actual data so that you meet the needs of all users.

Outdated or incomplete content

Schedule periodic reviews of your user guide, so that the developers can update any outdated content or fill in missing information. Products change; your documentation should change accordingly.

By scheduling regular reviews, you decrease the risk of misleading users. Providing inaccurate or incomplete documentation can destroy the credibility of your guide or even put consumers in danger.

Inconsistent structure or presentation

Presenting information in a consistent manner allows users to absorb content more efficiently. By establishing style and formatting guidelines and following them strictly, you help to reduce reader confusion.

Be sure to use styles to control the formatting of your paragraphs and headings. Also, present your chapters in a structured manner. Each chapter should be introduced and concluded in a similar way, so that the reader feels a sense of familiarity and comfort with the presentation of content.

By following the tips above, you should have a better chance of producing a helpful user guide. Try to stay focused on key tasks and on understanding your audience.

If you enjoyed this post, you might also like User guide writing tips.