HelpScribe

White paper writing | Strategies for success

noreply@blogger.com (Craig) — Thu, 29 Oct 2009 22:51:00 +0000

White papers are a fundamental part of your marketing arsenal. And if you think technical writers don't need to worry about marketing, read on to see why white paper writing is an essential skill, and how to turn a ho-hum paper into a killer communications tool.

If you are a freelance or contract technical writer, a strong white paper can help you land new clients. The primary difference between contractors who succeed and those who fail is that the winners are better at selling their services. Sure, you're a highly skilled technical writer. But if you can't explain to clients why your services are better than those of your competitors, you'll be a broke technical writer. A strong white paper can give you the edge you need to land bigger contracts.

And if you work 9 to 5 in a high-tech industry, don't think you're off the hook. Chances are a white paper will end up on your desk at some point. Why? Because you have the technical editing skills to be an effective reviewer of IT-related marketing documents. At a smaller company, you may even be required to pitch in and write such documents.

So, how do you produce a killer white paper? Here are some tips...

Know your audience

But I already know them. No, I'm not talking about knowing that your potential customers are mid-level managers with purchasing authority at corporations with 1,000+ employees.

I'm talking about really knowing them.

What problems are they struggling with that give them headaches or keep them up at night? What challenges stand in the way of them meeting upcoming deadlines?

And most of all, what can you do about it?

If you can answer those basic questions, you have the makings of a killer white paper.

Know what distinguishes you from your competition

Chances are your sales pitch won't be the first to come across the desk of your potential client. So, why should you get the sale?

If you can't clearly spell out what makes your services or products different, you'll watch sales slip away into the hands of your competitors.

Make sure your white paper clearly points out why your company is the best fit for the client. If you don't have a point of distinction, get one. In a competitive market, you have to distinguish yourself to consistently win clients and sales.

Show your mastery of the technical details

Bring your technical knowledge and research skills into play. If your paper displays even a hint of ignorance about the technical details of the client's problems, it won't make a great impression.

Nail the details, however, and you may win the client's trust. Use all of the resources at your disposal to verify that you are communicating a clear understanding of the technical issues your client faces. Talk to engineers and developers at your firm and find out what they know that might help solve the client's problems.

Master basic copywriting principles

Remember, writing white papers is about selling. If your potential client never reads past the headline, you won't get the sale.

Hook the reader early. Make the headline scream "I understand your problem; here is the solution..."

Every sentence carries the same burden. Keep the potential client reading, while at the same time communicating how essential it is that they contact you for the solution to all of their concerns.

Back up your pitch with proof

Can you find studies that add credibility to the solution you propose?

Do you have testimonials from past clients that demonstrate how wonderfully you solved their problems?

Don't just talk the talk; show clients that you can back up your claims with some solid evidence. The more leverage you can add to your argument, the more confident your new client will feel about signing a contract or making a purchase.

Evidence helps build trust, and trust makes the sale.

Make contacting you a no-brainer

Ok, so you've written a killer white paper that demonstrates how your product answers all of the client's needs. After reading it, they are imagining how successful they will be after partnering with you.

But then the phone rings, and the paper ends up at the bottom of their To Do pile. Later, the vision has faded, and they have forgotten what it was they were so excited about.

Don't let this happen. Instead, end your white paper with a clear call to action, including contact information for a sales person who can follow up with the client. The white paper will hook the client, but it often takes some hand holding to close the deal and form a mutually beneficial relationship.

With these tips, you should find yourself better prepared for writing white papers that win clients and sales. Good luck!

The Jetsons, and technology running amok

noreply@blogger.com (Craig) — Mon, 12 Oct 2009 00:52:00 +0000

Tonight I'm watching The Jetsons with my kids. It's a very enlightening cartoon. In fact, I've never seen a better argument for the need for technical writers.

Every morning George is flung from his bed and conveyed through a slew of machines that dress, groom, and feed him before flinging him into his jet car and sending him on his way. (I could REALLY use a setup like that.)

Unfortunately, these contraptions often fling poor Jetson into a wall, or leave him trapped in his bed matress.

Responsible engineers would never build such machines. However, accidents happen and products malfunction. (Don't get me started on my lawn mowers.) That's why well-written manuals and warning labels are such a big deal.

Every product is potentially risky. Somebody has to warn poor Jetson that spilling coffee on his jet car console could have disastrous results.

And can you imagine the maintenance required for such contraptions? Unclogging a plugged sink is a simple procedure; I get to perform that one often. But unclogging an automated hair trimming machine that also serves coffee would be an interesting challenge. (Better read the manual first.)

Sure, George can dial up his robotic handyman. But for those of us without such options, a well-written set of user manuals is the next best thing.

If you enjoyed this post, you might also like...

Training manual DOC files

noreply@blogger.com (Craig) — Mon, 12 Oct 2009 00:14:00 +0000

Writing a manual from scratch? A training manual template in DOC format will help you produce a high quality document using Microsoft Word.

You can get professional templates using the link below.

GET TRAINING MANUAL DOC TEMPLATES - The "User guide", "Training plan", or "Employee handbook" templates might serve your needs.

A template will lay out the format for your guide, prompt you for essential content, and help achieve a professional look and feel.

For information on writing your manual, try the following post.

How to write training manuals

How to archive documents

noreply@blogger.com (Craig) — Thu, 01 Oct 2009 00:14:00 +0000

Knowing how to archive documents is essential to an efficient workflow. Think about it; you work hard to create the documents your organization needs to be effective. Why risk losing that hard work? Archives ensure that you can recover any lost documents, and make it easier to track the specific details of your project the next time you work on it.

Here are a few tips for creating an effective archive for your documents.

Create a readme file and store it with your project files. The readme should also be archived along with the rest of the project. Readme files should contain essential details, such as the working path, a list of files in the project, notes from the last person who worked on the project, when the document was last delivered and archived, and so on.
Schedule your backup process, and automate it. That way your backups will be reliable even if everyone working on the documents isn't familiar with how to archive documents according to your conventions. Use the scheduled tasks features in your operating system to launch scripts that will automatically backup your files on a regular basis.
Zip your files. Compacting the project archive will reduce the amount of space your backups require, and make it faster to copy or move the files, if necessary.
Put your document archives on both a network drive (to take advantage of scheduled server backups), and on physical media, such as a CD or DVD. It's better to me cautious than to lose important project files and regret it.
Whether or not you compact (zip) your files when you archive them, be sure to maintain the folder structure. That way everything is in the correct place when you pull down the document files for the next update.

By following careful archiving procedures, you can decrease the risk of losing your files and make your workflow more efficient.

Document automation - Word

noreply@blogger.com (Craig) — Sun, 27 Sep 2009 15:21:00 +0000

This article contains tips and getting-started information for documentation automation with Microsoft Word.

MS Word has incredibly useful VBA features that allow you to automate routine documentation tasks. You can use the Record Macro feature to automate many repetitive actions, such as retagging paragraph styles, searching and replacing content, and so on. For advanced automation, use the Visual Basic Editor. The editor has many GUI features to assist you in writing code for complicated procedures.

Why automate?

Repetitive action is costly. How many hours does your documentation team spend performing the same actions over and over on the documents you produce regularly? When you analyze the time lost through such repetition, you can see how much more productive automation will make your team.

What is a Word macro?

Word stores automation code in the form of macros. Each macro contains the code necessary to perform a specific automation task. Often, macros are chained together to handle multiple taks.

You can view available macros from the Developer tab in the ribbon. Click the Macros button to view a list of macros available within your document.

Macros can be stored in individual documents, or in templates (.DOT files). I suggest storing them in templates, so that the macros will be available in all documents with the template attached.

The Macros dialog allows you to run, record, edit, organize, and step into macros.

Deciding what documentation tasks to automate

Some tasks are easier to automate than others. Here are a few quesions to help you decide if a task would benefit from automation.

Is the action you wish to automate exactly the same every time, or does each iteration require special consideration?
Can you summarize the steps involved in performing the action?
Do many people in your department perform the task regularly?
Does the task apply to many documents, or at least several long documents?

If you can answer Yes to most of these questions, chances are automation is worthwhile.

Recording a macro

Word allows you to record macros. This is the easy way to automate document tasks since it does not require you to write any code. Use the Record Macro feature on the Macros dialog to create a new macro. Then, perform the tasks that you wish to automate on the document you currently have open. Word will record your actions and write the macro code for you.

Click the Stop button when you are finished performing the tasks. Then, use the Run feature to test your new macro.

Recording macros and then editing them in the VBA editor is a great way to learn the VBA language. VBA is a flavor of the BASIC programming language, so it is easier to understand than many lower-level languages. Since you know what tasks you performed when recording, you can easily determine which chunks of code belong to each task.

Editing a macro in the VBA editor

Often the tasks you wish to automate are more complicated that what can be recorded in a single macro recording session. By working in the VBA editor, you can combine code from multiple recorded macros into a single, larger macro. You can also use the GUI tools to drag and drop code fragments for common document objects. You can also include more complicated code such as database connections and GUI forms for gathering information.

On the left side of the editor window, you'll see a list of the modules available in your template. You can store multiple macros in a module, or one per module. I recommend storing a single macro in each module to reduce confusion between module and macro names.

The editor also allows you to export your automation macros. However, for sharing and archiving purposes, it is often better to archive or share the entire template.

Each macro in the editor begins with a Sub statement and a name, and ends with an End Sub statement. All code between these statements belongs to that macro.

To include comments in your automation code, start the line with an apostrophe or a REM statement. Word will recognize this as a comment and will not try to execute it as code. Comments allow you to make important notes about the purpose of a block of code, so that you or others will have an easier time understanding it later.

As you develop more and more macros, you may find the Macros tab of the Organizer dialog useful. This dialog allows you to copy macros across document or template files. If you are sharing macros, it is best to just share the entire template, but you will find the Organizer tab useful for consolidating related macros and cleaning up your templates.

Wrapping up

As you continue recording and editing macros, you will find it easier and easier to understand the VBA language, and the types of features Word allows you to automate. Your document production process will become more efficient, and your bottom line will likely improve as a result.

Technical writers are building customer loyalty

noreply@blogger.com (Craig) — Tue, 22 Sep 2009 01:54:00 +0000

Think closely about the many technical products you've used throughout your life. Microwave ovens, CB radios, lawnmowers, DVD players, computer software... we're surrounded such products and depend on them.

Chances are you have favorites; perhaps a laptop computer or portable mp3 player.

Chances are you loathe some products, and avoid them at all costs. (In my case it would be the various lawn mowers and weed trimmers I've struggled to keep running. Parts just keep breaking or falling off.)

The products that become your favorites are likely those that you can use effectively. You are familiar with them, perhaps even an expert. You trust in your ability to use those tools to get the job done.

That's why technical writing is important. Writing a great user manual helps produce proficient users, and hopefully guides those users along the path to expertise. It's like introducing them to a new friend and helping them get acquainted. If you can help the user understand the technology, it will become like a trusted friend, and that user will look forward to future experiences with that tool.

Help your users sort out the details. Dispel their fears. They will reward you by becoming experts who will promote your products to others.

Writing instructions - template and guidelines

noreply@blogger.com (Craig) — Tue, 15 Sep 2009 10:45:00 +0000

Writing instructions that others can follow easily can be challenging. However, by following some basic guidelines and starting with a template, you'll find the process much easier. Here are a few tips to help you write effective instructions.

Use a template to assist your in structuring your document. For example, a user guide template will provide a basic layout for procedural instructions.
Get familiar with how procedures are written. This post on writing procedures will help you understand how to present your instructions clearly and in the proper order.
Find a volunteer to test your instructions. Usability testing is a great way to fine-tune your documents and make them easier to understand.
Clearly define the goals for your instructions. Users will have an easier time reaching them if the desired results are defined ahead of time.
Accompany procedural instructions with overview information. This will provide the background information for the procedures and help users understand the point of performing each procedure.
Clearly warn users of any risks or danger involved in the instructions.

By keeping your instructions brief and well focused, you increase the chances of your users completing them successfully.

Training plan XLS

noreply@blogger.com (Craig) — Tue, 15 Sep 2009 01:08:00 +0000

A training plan XLS (spreadsheet) can assist you in tracking all of the details for your training program. The spreadsheet format allows you to record and sort information such as list of attendees, equipment, procedures, and other data. Spreadsheets also allow you to link related information across multiple worksheets.

If you wish to find a spreadsheet for developing your training plan, you can find templates and spreadsheets here.

Don't forget to verify that the spreadsheet format can be accessed by everyone that needs to view the documents. You can open most spreadsheets using the free Open Office suite if you do not already have appropriate software installed.

Training plan document tips and templates

noreply@blogger.com (Craig) — Tue, 15 Sep 2009 00:44:00 +0000

Do you want to develop a highly effective training program? If so, training plan documents are essential. Careful planning and thoroughly documented details can increase trainee retention. Also, trainers will have an easier time delivering an effective training session if the details are nailed down in advance.

Here are some tips for creating useful training plans.

Start with a set of professional training plan templates. They will guide you through developing your plan by prompting you for essential information; also, they help to ensure a professional and consistent look and feel for your plan.
Consider the scope of your training. Is it targeted toward beginning, intermediate, or advanced trainees? By deciding upon the appropriate skill level ahead of time, you will have an easier time deciding what procedures to cover.
What resources are necessary for the training? Will trainees need computer or internet access, or other supplies? Provide the resulting list to the person in charge of acquiring them ahead of time, so that they will arrive on time. If trainees will need to bring anything to the training session, be sure to clearly communicate this ahead of time.
Assess what kind of training environment will be needed for the session. Will a large room with an overhead projector be necessary? How can seating best be arranged to facilitate communication among the trainees? If your training will take place outdoors, be sure to factor in possible bad weather and have a backup location available.
Work carefully with the trainer so that their needs are covered. Each trainer may have a different presentation style, or wish to cover specific areas of expertise. Outline such differences ahead of time and encourage the trainer to keep notes on such details.
Will the training program count toward certification of some sort? If so, you may need a means of tracking attendance so that all trainees receive credit. Perhaps a spreadsheet of attendees, including contact information, will be useful.

By carefully considering such issues ahead of time and documenting them clearly, you can increase the effectiveness of your training and make it a success for everyone involved.

Review of Conversation and Community - The Social Web for Documentation by Anne Gentle

noreply@blogger.com (Craig) — Thu, 10 Sep 2009 22:53:00 +0000

When I heard Anne Gentle was in the process of writing this book, I was excited. The initial buzz hinted at answers to questions being raised in professional discussion groups and in my own work, the most unsettling being "If users are resorting to community-generated documentation, where does that leave professional writers?"

When the publisher sent me a free copy to review, I couldn't wait to dig in.

New roles for technical writers

As social media digs its roots deeper and deeper into the lives of consumers, it is becoming clear that writers need to adapt and get involved. The old methods of documentation production and delivery don't always meet the needs of our users. The process is too slow. The resulting documents do not engage or involve users, or make efficient use of their feedback. Users are responding by searching Google instead of the product's help, and by starting their own product-based communities for asking and answering questions.

Anne Gentle sees this change in a positive light; she has jumped into the tangled world of Web 2.0 with both feet and emerged with a clearer sense of purpose. Through her experiences working on community-generated documents, she has discovered how writers can add value and authority to wikis, blogs, and other forms of social media. Her book is filled with insight gained from her work as a professional blogger, FLOSS Manuals veteran, and volunteer for the One Laptop per Child project.

The answers you seek are here

The initial pages of Conversation and Community - The Social Web for Documentation cover the various types of social media being used to generate documentation and product-based conversations. Gentle starts with the essentials, including wikis and blogs, but continues to suggest a vast range of tools along with details on how each applies to user documentation. Web 2.0 junkies might be familiar with some of this material, but I found quite a few suggestions that I hadn't considered before.

Then Gentle gets into the really good stuff. She covers, in detail, all of the nagging questions about how writers fit into this new world of social media. For example...

How to determine if your customers need or want an online community.
How to judge what features and information your customers will find useful.
How to judge what role the writer should play in a community.
A definition of the types of roles a writer can play.
How to ease your way into a community without being intrusive.
How to convince your company of the value of the social web for documentation.
Tips for implementing community technology and getting other writers involved.
Guidelines for measuring the success of your community-based documentation.
How to organize Book Sprints and grow a team for building a community-generated document.
Specific examples of FLOSS Manuals involvement and the tools used in Book Sprints.
Guidelines and tools for repurposing Wiki pages and other user-generated content.
How to find your voice and get involved immediately.

I could elaborate here, but you should really just read the book so you don't miss the vital details.

What I like best of all is that Gentle never makes the mistake of elevating the technology to greater importance than the people who use it. It isn't about the tools; it's about the community. It's about relationships.

My overall opinion

This is a very important book. Not reading it is like sticking your head in the sand and waiting for your career to dissipate into oblivion. Your community needs you.

BUY IT FROM AMAZON...

Examples of technical writing assignments

noreply@blogger.com (Craig) — Thu, 20 Aug 2009 02:46:00 +0000

Here are a few examples of technical writing assignments to help your students develop practical skills.

Several of these exercises involve working with existing user manuals. You may wish to find open-source documents that allow you to make copies for students, or consider using documents produced by your school, such as handbooks and internal procedures.

If you work with documents that have a more restrictive copyright, you can consider asking the author of the manual for permission to make copies for use in your technical writing assignments. If this is not possible, consider breaking your class into small groups so they can share a manual.

Many product manuals are available in PDF format and can be found by searching for "[product name] user manual" or just "user manual" in Google.

Assignment examples

Ask each student to find a user manual for a common household product. Have them read through part of the manual and try to categorize the content. Use different colored highlighters for each category (procedure, reference, FAQ, and so on).
Ask each student to interview an expert on a technical subject, take notes, and write a procedure. This can be as simple as asking a friend how to use a particular social media application feature that the student has not used before.
Volunteer to edit existing instructions for another department. For example, your school library may have instructions for accessing online resources or using software installed on library computers.
Read through this post on writing a user manual and discuss the workflow with the class. Why are reviews important? What technical issues are likely to arise while writing a user manual? See if they can answer challenging questions about the process.
Find a short printed manual and remove the table of contents. Ask the class to create a new table of contents based on the information within the manual. You can print copies of an open source manual, or divide the class into small groups so they can share.
Repeat the process above, but create an index instead of a table of contents. This exercise should be preceded with a discussion of indexing principles.
Ask students to find an example of poorly written instructions and rewrite them. Discuss the decisions students made during the rewriting process.
Discuss copyediting marks and methods, and ask students to perform a copy edit on a short technical document.
Ask students to write a few short procedures for using a household product. Then, have them trade and review the work of another student. You may want to start out with a discussion on writing review comments in a non-offensive manner, and on developing a thick skin for critical review comments.
Discuss the relevance of HTML and web-based media to technical writing. Then, pick a technical subject and have each student create a web page in HTML. Use a free web-hosting service such as 50webs.com to assemble these pages into a website.

Are there similar assignments that you find useful in your class? Feel free to share by leaving a comment.

Simplifying your documentation process - 10 tips

noreply@blogger.com (Craig) — Mon, 03 Aug 2009 21:59:00 +0000

Here are some tips for creating technical documents more efficiently.

Find exceptions (documents that require special treatment) and eliminate them whenever possible.
Use macros, simple scripts, and keyboard shortcuts to automate tasks that consist of repetitive actions across multiple documents.
Avoid enhancements that will result in a more complicated process, unless the ROI is very high.
Reduce the involvement of unnecessary people (reviewers that offer little feedback, etc.).
Create internal documentation for complicated procedures, but only if the process can't be made less complicated.
Eliminate documents that have a low ROI (those that are redundant or don't get used).
Avoid producing the same document in many formats; instead, focus on increasing the quality of the format that is most widely used.
Keep your document tracking tools and policies as simple as possible. Every bit of information you track costs future labor hours to maintain.
Use Readme files to store important notes with project files, but only if you're sure doing so will save time when you next update that project. Consider how long you'd spend tracking those details down vs. how long you'll spend maintaining the Readme file.
Create simple scripts for auto-generating your help projects and delivering your files.

Ok, so you won't always be able to throw tedious documents out the window. However, keeping these tips in mind will help you write technical documents with fewer headaches.

If you liked this post, you might also enjoy:

Should your help be moved to a server?

Developing an effective communication plan

noreply@blogger.com (Craig) — Wed, 29 Jul 2009 23:30:00 +0000

Developing an effective communication plan is essential for keeping your business communications running smoothly. Such a plan will help you ensure consistency and clarity in both internal and external communications, meet deadlines, keep key people informed, and allocate resources.

Here are some tips for producing a plan that will help your business meet its goals for communications.

Start by becoming familiar with the structure and purpose of communication plans. You may want to begin with a communication plan template to guide you through the process.
Contact key players early in the process and meet with them. Departments that produce documents, such as Technical Communications and Marketing, should be included. Also include any high-level staff that are in charge of overall communication strategies for your business. By including representatives from key departments, you can increase the thoroughness of your communication plan and make it more effective.
Gather existing notes on communication policies. Often these will be organized and distributed in an inconsistent manner. Writing a communication plan gives you a chance to consolidate them and make them easily accessible.
Ask interested parties for any deliverables lists, documentation schedules, deadlines, etc. produced in the past. This information will give you a head start in fleshing out your communication plan.
As you look over past communications, try to assess and categorize the audience for each. These categories will help you create policies for addressing each audience, so staff can refer to them for future communications.
Also try to summarize the goals for each type of communication. Your plan will help you formalize the goals, but the process will be easier if you already have a clear understanding. If you have questions, follow up with the staff responsible for that type of communication, and ask them to help you clarify the goals.
When the plan is complete, have all interested parties review for any inaccuracies.

Following these steps will help you produce a communication plan that helps your business reach its communication goals.

Resource: Marketing Plans, Sixth Edition: How to prepare them, how to use them

Technical communicators cannot be provoked

noreply@blogger.com (Craig) — Fri, 24 Jul 2009 02:47:00 +0000

Have you ever received a review comment that totally ticked you off?

Perhaps a sarcastic comment with no practical suggestion for improving the content? Maybe even one that questioned your abilities as a writer and the value of your contribution to the product?

The dangerous thing about being a writer is that you're well equipped for unleashing scathing replies. If your buttons have been pushed, chances are your retaliation will bite deep and leave no room for misinterpretation. After all, you sling words for a living, right? Like the hands of Kwai Chang Caine, your words are deadly weapons.

Hold that thought...

Entrenched

Imagine you are knee deep in water and holding a musket over your head. It is a dark night, and the shadow of the bridge you're hiding under blocks even the faint moonlight.

You can't stop shaking from the cold.

Through the fog, you hear the muffled screams of injured soldiers as the doctors do their best to keep them breathing. Your stomach cramps from hunger, but you hold your post. At all costs, you'll hold your post, because the bridge under which you stand is the only passage for incoming supplies. It represents food, reinforcement, and a path for retreat, if necessary.

For days you've held that post, and now it is the only thought on which your starved spirit can focus.

Suddenly you notice a flicker out of the corner of your eye. A torch?

Then, you see the surreal image of a soldier reaching out and lighting fire to the bridge. As it burns, all hope of ever reaching home drains from your body, and the night erupts with the sounds of chaos and fighting.

On bridges, and burning them

As tempting as it may be to fire off a biting reply to an obnoxious comment, you'd be setting fire to your own bridge. Across that bridge are your allies. They have the information you need to win the war against bad documentation, and writing great user manuals requires more than an army of one.

Before you blow that bridge into oblivion, consider the cost. Sure, you might feel a bit better after blowing off some steam. But in the long run, you'll have lost a valuable relationship.

Instead, take a five minute break and do something enjoyable. Maybe when you come back, you'll see the offensive comments in a new light. You might even arrive at an understanding of why they were written.

Perhaps the reviewer was just having a bad day.

Keep the peace and everybody wins.

(Is this post too melodramatic? Sure. But it least you read it to the end.)

Writing user manuals | tips and templates

noreply@blogger.com (Craig) — Wed, 24 Jun 2009 01:51:00 +0000

Writing user manuals isn't so difficult if you start with a clear understanding of the structure of such documents. This post will provide you with some guidelines for producing a great manual, and links to templates to help you get started.

Gathering information

The ultimate success of your manual depends heavily on accuracy. If you fail to correctly document how a product works, users will lose faith in the reliability of the guide and stop referring to it. Also, such mistakes can be dangerous and/or expensive for the user.

To ensure that your manual is accurate, refer constantly to the product as you write. Test each section of content against the actual product (or at least the specs) and watch for errors where the text doesn't match how the product works. Also, ask your SMEs (Subject Matter Experts) about any inconsistencies that aren't immediately clear to you. Often they can clarify how the product operates and make suggestions for improving the documentation.

Structure and templates

When you have a clear picture of how the product is used, start outlining the tasks users will complete. An outline will ensure that your manual is thorough, and ease the writing process. You may wish to show your outline to SMEs and have them verify that all tasks are included. If you feel comfortable in your knowledge of this information, you are almost ready to start filling out the details.

Your manual will begin to take shape as you fill in the details based on your outline. However, you'll likely find yourself distracted by formatting issues as you draft your text. Such issues are best handled by starting with a professional user manual template.

Templates provide a standard structure for your document, as well as consistent formatting. By starting with a template, you'll likely have a much easier time fleshing out the details.

The writing process

Most user manuals are a balance of procedures, reference material, and troubleshooting information.

Procedures guide consumers through each task that can be performed with the product. Tasks are stepped out into simple, ordered instructions.

The key to writing high-quality procedures is to analyze the task from a user's perspective and break each part of the process into a clear and simple command. Also, be sure to consider any issues that may arise depending on the goals of each type of user.

When writing your procedures, be sure to consider any danger or risk involved in each step. Protect consumers by including warnings when appropriate, and make sure such warnings are located where users will see them BEFORE performing the step.

User manuals often serve as reference materials. Not many consumers are likely to read an entire manual prior to using the product. Therefore, your reference information must be easy to locate, and clearly presented.

For this reason, most well written user manuals include tables, technical illustrations, and other types of content that are easy to scan. Such content is easy to absorb, especially by consumers who are visual learners.

Many user guides include a Frequently Asked Questions section. By providing answers to common questions, you can vastly reduce consumer frustration and possibly lower the number of incoming Support calls your company receives.

Navigation

Even well written user manuals can be neglected if consumers can't find the information they seek.

Preface your manual with a table of contents, and include an index at the end. Also, add cross-references to related information. That way users can quickly refer to information that is relevant to the task they wish to complete.

Such navigation aids can often be generated automatically from your word processing software. However, you may wish to make adjustments. The best navigation aids come from careful thought about what most users will be looking for, as well as a thorough understanding of how the document is organized.

Reviews

Formal reviews are vital for writing high quality user manuals.

You can distribute review copies in print or electronically, depending on the preferences of your reviewers. Electronic distribution, such as a Word DOC file, allows your reviewers to insert comments easily. Also, the comment tracking features allow you to see the source of each comment when multiple reviewers work in the same file.

Paper copies, on the other hand, allow you to maintain a paper trail for audit purposes. Also, some writers simply prefer to incorporate edits from a printed copy.

When choosing reviewers, think a bit about the kind of feedback you will get from each reviewer. Include at least one developer, a Support representative, and the project manager. If you work on a team of writers, have another writer review the guide, or do a quick pre-review pass.

Developers will likely give feedback about how the product functions, and correct for any recent changes in the specs. Be sure to verify that such enhancements will make it into the product when it is released.

Support representatives also tend to give detailed feedback on functionality. Additionally, their frequent contact with consumers allows them to point out common trouble areas that can be clarified in the user manual.

Project managers often have the authority to give you a final answer on pending questions, and sort out conflicting reviews. Also, they can assist with scheduling the final delivery date for the manual since they are responsible for managing the entire project.

Preparing for delivery

If you've written your manual with constant consideration of your users, you should now have a highly useful document to deliver.

Before delivery, be sure that all interested parties have signed off on the document and that all review comments were incorporated. Then, carefully flip through the document and scan for any formatting issues.

After delivering your manual for printing or shipment, take time to celebrate your hard work. Then, get ready for future updates, because R&D is likely planning product enhancements for the next release.

Hopefully these tips will help you produce documentation your users will enjoy and find highly informative.

Resource: How To Write Usable User Documentation

First time here?

noreply@blogger.com (Craig) — Tue, 09 Jun 2009 11:12:00 +0000

Welcome to HelpScribe. If this is your first time visiting, you might want to check out the following posts.

How to become a technical writer (my story and stories from other writers)
6 ways to improve user retention of help content
Why we become technical writers
Current trends in technical communications
22 tips for writing software documentation users will actually read
The art of technical writing

Also, don't forget to subscribe to the RSS feed. Just use the link in the navigation section.

Thanks for visiting!

Strategic use of FAQs on Communications from DMN

noreply@blogger.com (Craig) — Tue, 09 Jun 2009 10:42:00 +0000

I just wrote a guest post on the Communications from DMN blog about using FAQs effectively.

If you check it out, don't forget to subscribe to the Communications from DMN RSS feed. They publish highly informative posts on a regular basis, so you don't want to miss anything!

Why internal communications is the land of opportunity

noreply@blogger.com (Craig) — Sat, 30 May 2009 08:22:00 +0000

When we think of technical writing, most of us think of end-user documentation. However, technical writers have skills that can be leveraged inside the company as well. By acting as a communications service for other departments, technical writers can build a reputation for quality work and contribute to the bottom line.

What does this mean for you?

A lot, actually.

Greater respect from coworkers - You'll spend less time explaining what exactly you do, and justifying your existence to the powers-that-be.

Awareness of recent changes - You'll have deeper involvement in projects from other departments. This can mean earlier notification of changes that will impact the documentation.

Increased product knowledge - Through increased interaction with developers and engineers, you'll have more water-cooler discussions about how products function currently, as well as any enhancements being developed.

Networking opportunities - More cross-department projects leads to greater entrenchment within your company and opportunities for advancement. (And more invitations to food events!)

New skills - Inside projects often require skills that you may not get to exercise when working on end-user documentation.

How to get involved

Here are several ways technical writers can add to the efficiency and profits of an organization.

Reviewing the content produced by other departments for technical accuracy. Marketing materials, executive presentations, policy and procedures manuals, and similar documents can always benefit from a thorough review.
Assisting web developers with information architecture and taxonomy issues. For example, is the corporate website well-structured?
Q&A and related product testing. Technical writers are great at looking at the product from a user's perspective.
Developing case studies and assisting with specs.
Creating scripts and storyboards for multimedia presentations.
Producing training materials and reference guides for internal tools.
Assisting with the technical details in Sales documents and providing screenshots.
Developing flowcharts from use cases that can be used to guide the product design process.
Assisting with the automation (macros, workflows, etc.) of document production in other departments.

This list could go on forever, but it's late (early?) and I have to sleep sometime.

If you'd like to add to the list, please do so by leaving a comment.

Is your help missing vital information?

noreply@blogger.com (Craig) — Thu, 14 May 2009 23:00:00 +0000

There's a lot of evidence indicating that online readers have short attention spans, and that we should dumb down electronic content accordingly.

In fact, I myself have suggested simple FAQ-based help in past HelpScribe posts.

But... there are two sides to every story, and I think it's necessary to tread with a bit of caution. Reader attention likely varies quite a bit, and making the help too light-weight can cost you in the long run.

While it may be vital to address those users who are looking for a quick answer to a problem, I'm guessing there are still quite a few users who work through the tutorials and soak up overview topics to become more efficient with a product. These are the hardcore users who love the product and want to know everything they can.

Even if these power users are a minority, we still need to pay attention to their needs when drafting help.

Why?

Because these power users are the same online-gurus who participate in forums, create product-related blogs, and spread messages all over about your product. They are the evangalists who can make or break your sales.

Should you make your help granular and answer specific questions? Yep.

But not at the cost of excluding important details that can turn casual users into experts.

Does your help encourage expertise?

Guide to writing standard operating procedures

noreply@blogger.com (Craig) — Thu, 14 May 2009 00:31:00 +0000

Looking for a guide to writing standard operating procedures, and templates to guide you through the process?

SOP documents are very important for ensuring that your organization or business runs in a safe and efficient manner.

For $9.99, you can get both a guide and templates that could potentially save many hours of work.

GET YOUR GUIDE AND TEMPLATES (See the "Standard Operating Procedures" section.)

The guide comes with multiple templates (Word and Excel) to guide you through the writing process and make your work easier. You'll also get other tools to help you produce high-quality SOP documents, such as information on standardization and regulatory requirements, and spreadsheets for documenting roles and responsibilities.

Also, your purchase through the affiliate link above helps support this website.

Important documents such as standard operating procedures should be written with care. Hopefully these resources will help you create the SOP documents you'll need to succeed.

Resource: How to Write Policies, Procedures & Task Outlines

Definition of technical writing | What is it?

noreply@blogger.com (Craig) — Wed, 06 May 2009 05:05:00 +0000

Technical writing is the act of documenting how to use high-tech products. This definition is broad because the field itself is vast. Those who work in the field are employed in a huge array of industries, including medical, automitive, software, training and consulting, and more.

A technical writer works closely with the engineers and product developers to draft instructions for using the product. The writer must interview the developers to find out how the product works, and then write clear instructions that can be understood by average users.

The final product can take the form of user manuals, online help, training guides, installation guides, quick-reference sheets, white papers, and more. Some technical writers also work on proposals. Others draft instructions that appear on packaging, or warnings stamped directly onto products. You can read more about writing technical documents in Technical Communication (Amazon.com affiliate link).

The process requires highly developed language, project management, and technical skills. Also, people skills are important for gathering information and working with the many departments within an organization that have feedback on documents.

For more information, see the following posts:

Writing technical documentation

noreply@blogger.com (Craig) — Wed, 06 May 2009 04:36:00 +0000

The process of writing technical documentation can be enjoyable if you follow some basic principles. The tips below should help you to produce high-quality instructions for your users.

Stay user-focused. Remember, not everyone knows what you know. Develop profiles of different types of users, and double-check your documentation against the profiles often.
Outline the tasks users will perform with the product, and then start writing. Don't worry about the technical details until you have a clear understanding of what should be included in the manual.
Avoid jargon. Most people don't have the technical knowledge of an engineer, or the linguistic abilities of a professional writer. Speak in plain language.
Think safety first. If the product can cause injury when used in the wrong manner, be sure to include appropriate warnings and draw attention to them.
Follow these guidelines for drafting effective procedures.
Interview subject matter experts so that you have a clear understanding of the product you are documenting.
Schedule formal reviews so that other experts can check your work, and don't take corrections personally. Many such corrections and reviews will be necessary if you want to produce great documentation.
Explain to readers the benefits of reading your document. Otherwise they may not be motivated enough to learn to use the product effectively. If they can increase productivity by 10% using your instructions, tell them so.
People often read instructions only when they run into problems. Provide troubleshooting tips that address specific questions and issues.
Be open to communicating directly with users. Feedback tools, forums, usability studies, and other user contact will help you get a clearer understanding of how users interact with a product.

If you follow the guidelines above, the process of writing technical documentation will be much more enjoyable. Your users will thank you!

If you enjoyed this post, you might also like the following:

Technical writing and communication

noreply@blogger.com (Craig) — Wed, 06 May 2009 04:02:00 +0000

The field of technical communication is growing fast. As technology progresses, there is an increasing demand for writers who can explain how products work. These products can range from simple instructions on a box of macaroni and cheese to more complicated procedures for using high-tech medical equipment.

The primary goal of the writer is to act as a user advocate. This means teaching the user how to use products effectively and safely.

Many skills are required for clear communications.

Basic writing and editing are a necessity; often, jargon can obscure the clarity or meaning of the instructions. Most who work in the field have a degree in English, Journalism, or a related course of study that builds language skills.

Graphic design and layout skills are important, especially during the initial phases of product setup. Templates must be designed to guide the writing process and ensure consistency.

Computer skills are of great value. Technical writers produce much of their work on computers, either in word processing programs or user assistance tools.

A general aptitude for technology is also beneficial. Writers must work with subject matter experts to learn how products work. Great documentation depends on asking the right questions and verifying the accuracy of the instructions.

Tech writing can be a very fulfilling field to those who enjoy both language and science, and can adapt to changing roles and projects.

If you enjoyed this post, you might also like:

So, what are you working on?

noreply@blogger.com (Craig) — Fri, 24 Apr 2009 11:30:00 +0000

Is anyone working on anything interesting? Or stuck on something frustrating? Let's take five minutes to vent and share our thoughts.

I'll start.

I'm getting ready to upgrade to the Adobe Tech Comm Suite v.2, and then I'll be digging my way through a slew of consulting guides that need to be updated. No headaches at the moment; there's too much sun outside to worry about anything.

Ok, your turn.

What are you working on?

Great book on social media and economics

noreply@blogger.com (Craig) — Fri, 24 Apr 2009 11:22:00 +0000

I'm plowing my way through Yochai Benkler's The Wealth of Networks. It's a thorough analysis of the productive power of social networks, and the implications of peer production on our market-based economic system.

If you have an interest in social networking, intellectual property, and economics, you might want to check it out. It's a long read (over 500 pages), but filled with insight.

As a writer, and a Web 2.0 user, I'm finding it much more applicable to my daily work and interests than I expected.

Hopefully I can make it through the whole PDF before my motivation wears thin. (Hard to do when it's seventy degrees and the fish are biting.)