How to write training manuals

Before you start your first draft, you should have an understanding of how to write training manuals that are effective in helping users learn the necessary tasks and skills.

This post will serve as a basic primer on how to write training manuals.

Getting started

You'll want to start by deciding what type of documents your training will require. Depending on the type of training you are offering, you may need to create one or more of the following documents.

• Training plan: For planning and tracking the details of your training sessions.
• User guide: For walking trainees through the procedures of using a product or performing a task.
• Employee handbook: For communicating importand procedures and policies necessary for job training.

You can download templates here for all of these documents. Click the link and choose either "Training plan", "User guide", or "Employee handbook" to view template details.

A professional template will provide you with rough outlines of exercises, procedures, and all the other necessary types of content your training manual will need. This will drastically increase your efficiency and help guide you through the writing process.

Self-guided vs. instructor-led training

As you write your content, you should have an understanding of how the training manual will be used. Will users guide themselves through the training process using your manual? Or will they sit in a live class with a professional trainer?

Self-guided training manuals must provide more thorough instructions than instructor-led training. Transitions between tasks become increasingly important. When a user completes a section of the manual, they must have a clear understanding of how the skills learned in that section prepare them for the next section of training. Summaries and introductions will help to give users closure and prepare them for what is to come.

Also, when writing for self-guided training, you must ensure that any possible technical issues or other obstacles are considered. If a user has problems completing a task, they will not be able to proceed to more advanced sections of the guide. Try to anticipate such trouble areas and provide a means for users to resolve them.

Instructor-led training, however, takes some of the burden off the manual. A professional trainer will be guiding users through each learning task. In such cases the manual serves as an outline for the trainer and users. If trainees run into problems, the trainer can assist with troubleshooting. Therefore, less detail is necessary.

For instructor-led training, you will want to develop a strong relationship with the trainer. They will talk with you about how to write training manuals that serve as memory aides for guiding their verbal presentation of the content.

Writing the content

Begin by outlining the tasks that trainees should learn. This outline will help you organize tasks into a logical order. Often the completion of a task will depend on previous steps having been completed. Skills will build upon other skills. Your outline will help you resolve such dependencies and present information in a sensible order.

Be sure to break sections into easily digestible chunks so that users aren't overwhelmed. Also, these shorter chunks will help the trainees feel confident that their skills are improving as they work through each section of the manual.

If you are working with a trainer, be sure to get their approval of your outline. Their feedback is essential. They may even provide an outline for you.

When your outline is complete, start drafting the procedures necessary to complete each section of training. Be sure to perform the steps in your procedures to verify that they are accurate. For tips on writing procedures, see 11 tips for writing incredibly useful procedures.

Consider whether trainees would benefit from some form of testing throughout the process. For example, you may wish to provide a short question-and-answer section at the end of each chapter of the guide. These short quizzes will help trainees determine whether they have successfully learned the skills presented in each chapter. If you have trouble coming up with questions, work with the trainer to develop some appropriate content for short end-of-chapter quizzes.

Data issues for software training manuals

If you are preparing a manual for a software training course, you may have to test any data that is used in the training to ensure that it matches with the data shown in screenshots and written in the instructions.

Ask the trainer to provide any data files that will be used in the training session. Use this data when shooting images of screens. Then, as you write the text, verify that the results from calculations and any other information matches with descriptive text in the guide. Take notes on any discrepencies, and share them with the trainer, in case the trainer wishes to modify the data.

This process of verifying data should also be performed during guide updates. If you update your manuals on an annual basis, be sure to review the data and any screenshots as well to make sure they remain consistent with the text in the manual.

Documentation reviews and publishing tips

After completing your draft, give the manual to the trainer for a formal review. If you are developing self-guided training you can ask another writer or a product developer to review your work.

Use reviewer comments to develop a final draft of the guide. At each phase of the process, be sure to test the accuracy of your procedures and keep a user-oriented view. Often your knowledge of the process or product will differ greatly from their knowledge.

Before you consider the job complete, run through a list of things to check before publishing a manual.

When your training manual is finished, rest assured that updates will be required. Products and procedures change over time. Use the update process as an opportunity to keep your product knowledge up to date, build relationships with trainers, and enhance your ability to see the process from a user perspective.

Hopefully the technical writing tips in this post will give you a basic understanding of how to write training manuals.

Related topics:

Download training document templates

Writing a training manual - tips and templates

Full text search vs. keyword search

Lately I've been pondering whether users are better served by full text search, such as the search functionality in most web browser help formats, or a human-edited keyword search with ranked results.

Full text search

The full text search results in many help formats can be overwhelming to users. In a large help project, users could easily be presented with 50 to 100 topic titles, all listed alphabetically. How do they decide which is most relevant?

Are users likely to scroll through such a large set of topics, clicking anything that sounds promising until they find an answer to their question?

Full text search, however, does offer a complete set of results. If a single obscure reference to the search phrase is buried in the bottom of the topic, users will be able to find that topic in the results.

But is a complete set of results the most helpful format for a majority of users?

Keyword search

What if the majority of users could find their answers faster by clicking a ranked list of results, similar to Google? Keyword search allows help authors to present what we think are the topics most likely to answer the majority of questions for a given search term.

If a user searches on "printing reports," chances are the "Printing reports" procedure is going to provide the answer, right? So shouldn't that topic appear at the top of the list of search results?

Keyword search can be tedious to set up. It requires indexing your content and studying past user search data. But maybe such an effort is worthwhile if more users find what they are looking for in the help.

A combination of both

Eventually I think help authoring tools will offer a combination of full text search and ranked keyword search to appear in the same help system. (Adobe, MadCap, are you listening?) That way we can present users with a few promising topics that will likely answer their question, followed by a complete list of topics for the users who are looking for less predictable instances of the search term.

Does anyone else have thoughts on this issue? Leave a comment!

Essential technical writing authoring tools

Not all tools are created equal. Some technical writing authoring tools have proven themselves to be key industry standards that have stood the test of time and put tons of quality documentation in the hands of users. These are the tools that should appear on your resume, and that should be on your hard drive if you want to produce great documentation using feature-rich tools.

Help Authoring Tools

RoboHelp - In spite of its dramatic past (see "The king is dead!"), RoboHelp is still the tool to beat when it comes to authoring help. Whether you are delivering web browser help or locally-installed CHM files, RoboHelp delivers. Adobe's dedication to improving the product has been impressive and RoboHelp just keeps getting better.

Flare - The only real alternative to RoboHelp. When Macromedia neglected RoboHelp, much of the development team left to create Flare, and many technical writers followed. The Flare team added innovative enhancements such as support for variables, a highly customizable interface, and an editor that provided new ways to view content. Also, the MadCap team has assembled a lineup of products that can compete with the Adobe tools.

Word Processing Tools

FrameMaker - Frame shows up in just about every technical writer job description I see. Why? Because its ability to handle large documents without corruption, render page layouts in a consistent and intuitive manner, and fit into a structured authoring workflow make it an essential tool for writing manuals.

Word - Word has entrenched itself as a viable alternative for technical manuals simply because it is installed on almost every business machine in the world. Sharing and reviewing documents is much easier when everyone in the company has the same software installed. And features? Word is packed full of them. If FrameMaker isn't in your budget, or if you don't need to handle large, structured documents, rest assured that Word is probably going to get the job done.

PDF Publishing

Acrobat - Acrobat is clearly the leading PDF tool on the market, having started the PDF format in the first place. The Adobe Reader is free for everyone to download, and most of us do. 'Nuff said?

Those are the essential technical writing authoring tools that most of us have installed.

If you are looking for a complete package of tools, check out the Adobe Technical Communication Suite.

The authoring tools listed above are especially essential if you are a contractor who frequently works on documents produced by others, or if you are starting a new technical writing team. (You can't go wrong by choosing time-tested tools.)

Some may argue that the list needs a screen capture tool, a demo tool such as Captivate, or an image-editing tool. Perhaps. However, I think many of the tools on the market would work just fine for such tasks.

Those of you who disagree, let me know by leaving a comment. Other readers will appreciate your thoughts.

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

• Embedded user assistance tools needed
• Free technical writing authoring tools
• Software for textbook writers

Improving the review process with wikis and project management tools

How often have you had the following experience?

You send an important document out to reviewers... they respond with conflicting edits. You follow up with them via email to resolve the open issues... and they reply with more conflicting edits.

Then you run around in person trying to get some answers they can agree on only to find one of your reviewers has left for vacation.

This is when you start reconsidering your career and thinking seriously about that taxi driver position in Siberia that you turned down.

Why reviews are tedious

Let's break down the problem.

• Reviewing in print doesn't allow reviewers to compare notes or see each other's edits.
• Electronically routed reviews do not allow the first reviewer to see what the last reviewer has changed.
• Often the wrong people are included in reviews.
• Scheduling issues make it difficult to receive all reviewer comments in a timely fashion.

Wow. That's a lot of headaches.

A better approach?

Reviews don't have to hurt. Wikis and web-based project management tools can address most of these issues.

Wikis, as well as the document repositories in web-based project management tools, allow reviewers to log in and view your document in its current state.

If a reviewer makes some changes, they can log in again later to see how those changes were impacted by later reviews. They can make more edits if they wish. The latest version is always available.

The discussion tab in a wiki or web-based project management tool allows reviewers to communicate about suggested changes. All issues are resolved right in the open for anyone to see. This eliminates the need for the writer to act as a moderator. You may still need to ask reviewers to clarify something or come to a consensus, but you can do so from the comfort of your office chair and trust that everyone had equal opportunity to respond.

Deadlines are helpful. Tell your reviewers to log in and make their changes, discuss any issues amongst themselves, and come to a conclusion by the end of the day (or whenever) so that you can finalize and publish the document. A wiki takes the pressure of the writer by giving reviewers the tools they need to come to a consensus.

Wikis and project management tools also make it easy to include all relevant people in the review. Anyone with access rights can log in and participate, and a firm deadline will keep even a larger number of reviewers on task.

You'll still have some difficult issues to resolve now and then. For example, if your SME is on vacation and can't log into the wiki, you won't get a review. But wikis and project management tools can take a lot of the pain out of the review process.

How to convert CHM help files to web browser help

Converting your CHM help files to web browser help doesn't have to be a painful process. With the right tools, you should have no problems.

First, download Microsoft's HTML Help Workshop. It's a free download, and you'll need to it decompile your CHM.

Now you have everything you need to convert CHM help files to web browser help. At this point you should consider investing in a help authoring tool such as RoboHelp if you don't already have one. After you decompile your CHM, a tool like RoboHelp will make assembling all of the individual topics into a complete web browser help system much easier.

To decompile your help, launch HTML Help Workshop and choose File / Decompile. Specify a CHM file to decompile, and an empty folder where all of the decompiled files should be placed. Now click the button to decompile your CHM.

The decompiled files are the building blocks for your new web browser help. You can now build your own navigation system in HTML and handle the publishing process yourself, or use RoboHelp to make the job simple.

In RoboHelp, create a new WebHelp project and then import the HTM files that you decompiled previously. You can also import CSS stylesheets, TOC and Index information, scripts, etc. After you have imported all of your source files, click the Single Source Layouts option in the RoboHelp Explorer window and specify your project settings.

Now click the Generate button and you'll end up with a complete web browser help system that you can share with your users.

Converting CHM to HLP is a bad idea

According to search engine statistics, a lot of people are searching for information on converting from CHM to HLP. If you are considering such a move, there are some things you should be aware of.

First, HLP support has been dropped by Microsoft. The viewer doesn't even ship on Vista machines. So if you have users that might be on Vista, they won't be able to view the help. Users might be able to download the HLP viewer (I'm not sure), but do you really want to make your users suffer through that just to get help?

Second, the HLP format really shows its age. The look and feel of an HLP will make your software seem dated and clunky.

Most people are migrating from CHM because CHM files don't work anymore when launched from a server. Instead of converting CHM to HLP, you can convert CHM help files to web browser help formats like WebHelp or .NET Help. These formats offer a greater deal of flexibility and functionality, are supported by modern tools like RoboHelp, and are perfect for server deployment.

How to improve your help by mining user forums

User forums can be a real gold mine for finding topic ideas to round out your product's help. Often such forums receive an incredible amount of traffic. Why? Because they give users quick answers that help them complete specific tasks.

Think about it. Most users are trying to complete a specific task using your product. They don't want to dig through reference documentation to find the details. If a user can't start his lawnmower, why put him through the misery of an overview of the internal combustion engine?

A forum, however, is like asking, "Hey Carl, what's wrong with this lawnmower," and hearing "Ain't got no gas in it."

Problem solved.

Here are some ideas for turning forum conversations into help, so your users can find the answers they need right away.

Monitor recent posts

Check forums regularly for new posts. When you see one, look at the number of users who have viewed the post. Is it high compared to other posts of roughly the same age?

If a new post is receiving a lot of traffic, search your help to see if you've provided an answer already. If so, perhaps you need to revise the title so that it more closely matches the post title. Users may not be recognizing your help topic as an answer to their problem.

Write new FAQs and procedures

If the help doesn't address the issue discussed in the post, it's time to create some new help topics.

First, write a short and highly focused FAQ with a title similar to the post title in the forum. Don't argue with the evidence; the high post traffic tells you the post title is essentially on target. Clean it up, but make sure users would still recognize your topic as addressing their issue.

For conceptual problems (e.g. "Does the Date of Birth field require a 4-digit year?") a FAQ alone might be sufficient. If the forum post suggests a few steps, you should draft a procedure.

The post itself will outline the essential steps of the procedure. You'll just have to organize and edit the long-winded conversation into something elegant and more usable. When your procedure is complete, create a link from your new FAQ to your procedure.

Make your answers easy to find

Now that you have some tightly-focused topics to offer, make them easy to find. Here are some tips for doing so.

• Organize your FAQs into a list categorized by subject matter so users can quickly navigate down to the more granular topics.
• Make sure your FAQs can be searched from Google, not just your help viewer.
• Put a checkbox next to the forum's Search field that says "Include product documentation in search results." Many users will prefer a well-written FAQ to a user conversation once they realize an official answer exists.
• Ask the team responsible for maintaining the forum for a report of search keywords entered by users. When you know what phrases users are searching for, you can write your help topics appropriately.

Follow these tips and your users will soon have a greater respect for your help. They'll find the answers they need quickly without having to scroll through confusing or inconclusive forum conversations.

Next time I'll talk a bit about the benefits of using wikis and project management tools for turning SME conversations into finalized documentation. No more tedious conflicting review comments! (Subscribe so you don't miss it!)

Free technical writing authoring tools

If I was a new technical writer trying to get started on a budget, I'd likely take the free tools route. Free authoring tools have come a long way, and in most cases are robust enough to compete with proprietary tools. These tools would allow a new writer to produce a full set of documents and learn the production process without spending a dime.

Here's what I'd install...

Task: Word processing

Tool: Open Office

Open Office contains a full office suite, including the excellent Open Office Writer. Writer is packed full of useful features and looks and feels much like Microsoft Word. It can convert your documents to PDF without Acrobat. Also, Open Office uses XML as its native file format, making future portability a breeze.

Task: PDF creation

Tool: PDF Creator (affiliate link)

PDF Creator is a robust and inexpensive alternative that allows you to create Adobe compatible PDFs from many kinds of documents.

Task: Help development

Tool: Microsoft HTML Help Workshop

The Help Workshop compiler allows you to import HTML files and build a fully functional HTML Help system. It has tools for creating a Table of Contents and Index, and robust help for guiding you through the process. You can save any RoboHelp vs Flare worries for later, when your budget isn't so tight.

Task: XML editing

Tool: Cooktop XML

Cooktop is an "under the hood" editor, not the WYSIWYG variety. However, it has robust editing features, syntax highlighting, and allows you to specify an XSLT file for transformations.

Task: HTML editing.

Tool: Nvu

Nvu offers tabbed editing, WYSIWYG view, FTP and publishing tools, and other robust features to compete with the big guys. If also boasts full support for XML, JavaScript, and CSS. What else could you want from a free HTML editor?

Task: Graphics editing

Tool: SerifPlus 4.0

This free version of SerifPlus supports numerous file formats, easy-to-use wizards, and some really great drawing tools. And you can always upgrade to version X2 if you want to shell out some cash for the latest features.

That's it. Those are the free tools I'd use to learn the publishing process and create professional quality documents on a shoestring budget. Obviously you'll want to reconsider this toolset when your budget increases, but these free authoring tools will get the job done.

Are there any great freeware tools that you'd like to recommend?

If you enjoyed this post, you might also like:

• Essential technical writing authoring tools
• Software for textbook writers

Why wikis won't kill technical writing

Many people have predicted that wikis will replace traditional help in the future. Ok, I can buy that.

But I've also heard that technical writers will surrender content control to SMEs and users, and will move into other roles such as merely editing wiki content, or switching to programming, training, etc.

Sorry. I just can't see that happening.

In the world of wikis, technical writers will still be kings of content. Here's why...

Organization

If you've ever read through wiki or forum discussions between users or SMEs, you're probably aware that unorganized information is not user friendly. A usable wiki must have an intuitive structure. Technical writers will likely fill that role.

Information architecture is one of our primary skills, and a technical writer or help author will have an existing knowledge of how to organize the documentation because of previous experience organizing help and print content.

Extensive cross-referencing will also require a technical writer. A user or SME may think to link to a related procedure, but it will be a technical writer who replaces that single link with a comprehensive set of cross references so that it is helpful to a wider number of users. In fact, the writer will likely reformat an existing set of related links taken directly from the help. Extensive cross referencing would be difficult to anyone without a big-picture view of the documentation.

Generating content

Will users write helpful troubleshooting content? And will SMEs be better equipped to verify that the content is accurate?

Absolutely.

But will either bother to provide comprehensive documentation, such as a complete set of installation instructions or system requirements? How about an introduction to the product for new users?

Not likely.

A single user or SME won't usually have the time or inclination to do so. Users are more interested in answering task-related questions. Developers have higher priorities, such as improving the product itself. SMEs may review content, or provide chunks of information related to their individual component of the product, but aren't likely to spend time writing comprehensive instructions or providing cohesion between their content and information from other SMEs.

Technical writers, on the other hand, are devoted to the documentation. They have the information-gathering skills to turn unrelated chunks of notes into something that won't leave readers scratching their heads.

Managing the documentation

The best wikis will be written by technical writers, with tactful references to user forums when appropriate. Reviews and conversations with SMEs will be delegated to the Discussion pages of the wiki. Technical writers will then finalize that information by moving it into the Guide section of the wiki, so that users don't have to wade through a meandering jargon-filled conversation that may or may not provide any useful information.

The Guide section of the wiki will be locked down to filter out noise. Login will be required. (For example, see the Blender wiki. New writers need to request editing privileges and work with an existing author, and new content is sandboxed.) A documentation team will still be necessary to manage the wiki, just as they managed the old help and print content.

In short, technical writers will be doing the same job we always have. We'll just be using a new tool that offers some very promising features. We'll have improved communication with both users and SMEs. Everyone wins.

Will technical writers delve into programming, training, usability, and other tasks? Sure. But we've always had to wear lots of hats, haven't we?

At the end of the day we'll still call ourselves technical writers.

I'm looking forward to wikis. Are you?

Related:

• Review of Conversation and Community - The Social Web for Documentation by Anne Gentle
• Great book on social media and economics
• Social media news site for technical writers

Simple ways to improve usability of help

According to Jacob Nielsen's How Users Read on the Web, usability of web content can be improved drastically by making content more scannable. Many of his ideas would apply equally well to online help. So, how can technical writers leverage this information to make the help for their product more usable?

Use granular topics

Long reference topics and procedures should be broken into smaller, granular topics that users can scan. Often users lose confidence in the help because they cannot find the information they are looking for, even when the information is present in the topics they are viewing. It just isn't presented in a format that is easy to digest.

Break your topics down into smaller chunks and users will have a better chance of spotting the information they need.

Add subheadings and mid-topic jumps

Use meaningful subheadings and mid-topic jumps to allow users to quickly scan for and access the content they seek. Don't make them read through long topics packed with information that is unrelated to the task they are trying to complete.

Use a flowchart

Graphics are much more scannable than text. For complex procedures, provide a flowchart to help users quickly grasp the overall process. Link each step in the flowchart to a related procedure.

Organize your table of contents

If your help includes a table of contents, be sure to structure the table of contents so that it accurately reflects the organization of the help. The table of contents serves as a conceptual map of your help. An accurate map will help users quickly find the content they seek.

Step out lengthy procedures

Use a numbered list for procedures instead of stringing together sentences, and limit each step to a single task (or a couple of smaller tasks).

Users access the help when they are stuck. They may already be half way through the task described by your procedure. By stepping out procedures into smaller, scannable steps, you allow users to quickly jump into the procedure at the appropriate step to complete their task.

Use bulleted lists whenever possible

If your help contains lists of features, prerequisites for a task, or other list-type information, be sure to format the content appropriately. A bulleted list is more scannable than sentences in paragraph format. Also, each individual bulleted item will stand out to users, thus decreasing the possibility of a user overlooking any single item.

Emphasize when appropriate

Be judicious in your use of bold and italics. Too much of either will decrease the overall impact and distract users from the content that is really important. Use bold or italics for emphasis when it matters most.

Link related topics

Hyperlinks are one of the most useful features of online help. They also make your content easy to scan.

Use hyperlinks carefully to take users only to content that is related to the task they are trying to complete. The overuse of hyperlinks is not only a distraction, but it also can take users away from the very content they seek. Be careful when including them in the middle of a topic. Put related hyperlinks at the bottom of the topic, so that users aren't steered away from important material.

Hopefully these tips will improve the usability of your help, and allow your users to quickly scan for and find the information they need.

If you enjoyed this post, you might also like For technical writing, user feedback is essential.

The importance of software documentation standards

In a recent discussion on Tom Johnson's blog, Tom and others were trying to nail down the reasons why many users have a negative impression of help. Most people have used help before, but few seem to find the answers they are looking for.

The post left me wondering if much of the problem is due to a lack of standards in technical documentation. The look and feel of a help system can differ greatly from one product to the next, as can the writing. So how can the technical writing community emphasize the importance of software documentation standards and create a more unified help experience that users can adapt to?

Some users may be alienated by the lack of a standard help viewer. .CHM files are slowly fading into the sunset because they don't work when launched from servers. WinHelp is long dead. Most technical writing authoring tools now produce browser-based help, but the look and feel of HTML-based help can differ greatly from one tool to the next. There is no standard help viewer.

The lack of a standard viewer can cause a lot of grief for users. How can they trust the help as a source of information when they have to acclimate themselves to a new help interface for every different software product they use? A standard viewer would make it much easier for users to find the information they are looking for and leave with a positive impression of the help.

Negative user experiences also demonstrate the importance of standards for organizing and writing help content. The way topics are organized differs greatly from one system to the next. If a user expects to find links from dialog-level help topics to reference information, they might not revisit a help system that does not provide such links, but instead requires that they access reference topics from an Index. The usability of help systems in general would be enhanced if best practices were documented by standards organizations and followed by help authors.

Unfortunately, a standard help viewer doesn't appear to be on the horizon. Nor does a standards organization to promote best practices for structuring and writing software documentation. Perhaps one day these resources for technical writers will become available. Until then, help authors will simply have to make their individual help as user-friendly as possible and hope that their users are smart and determined enough to dig around and find the answers they seek.

See also: How to write a disaster recovery plan

Best of January 2008

January 2008 was a great month for HelpScribe Technical Writing. Not only was it the first month, but it was also packed with great posts for technical writers. Here are some highlights...

• How to convince others of the importance of documentation
• 9 tips for writing better FAQs
• Why write instructions that no one is going to read
• 11 tips for writing incredibly useful procedures
• Our .CHM files don't work anymore. Why?
• Can I download the Microsoft Manual of Style for free?

Thanks so much for reading, and for your participation. I hope these posts make your technical writing career a bit brighter. Enjoy!

Editing guidelines for software documentation

Software documentation can be difficult to review, so it helps to have some editing guidelines to keep you focused. Let's face it; software documentation isn't exactly exciting reading material. But you should be able to complete the job in a productive manner if you keep your coffee cup full and follow the editing guidelines below.

First, make separate passes for accuracy and grammar. This is one of the most important editing guidelines to follow. The human brain can only focus on so many things at once. If you are focused on verifying the accuracy of the software documentation, your mind will miss errors that are not related to the correctness of the content. Your first read through the software documentation should be limited to making sure the procedures are correct. When you are finished, read through the documentation again to fix any grammar, formatting, or punctuation issues.

Check the content against the product. Your software documentation should match the product interface. If your software has a "delete" button, the documentation should not call it the "erase" button. Carefully compare the steps in the software documentation to the menus, toolbars, dialogs, and field names in the software.

Follow a printed checklist of editing guidelines. Your editing will be much more productive if you have a printed list of things to check. This will also help you stay focused when your eyes began to glaze over.

Talk to the technical writer if you have questions about the software documentation. Most writers will be happy to discuss any issues with you, and will appreciate your involvement. Many are used to dealing with reviewers who do not appreciate the importance of documentation, and you will win some respect if you make an honest effort to help them document things correctly.

Trust the writer. You may prefer to reword some of the text, but don't be offended if the technical writer changes it back. Often they have certain internal conventions that they must follow to keep the software documentation consistent with other documents. Some editing guidelines are more easily to follow, but you really need to let go of any control issues if you are going to be a productive editor. Your relationship with the writer will improve drastically if you show trust in their expertise.

Hopefully these editing guidelines will help you stay focused the next time you review some software documentation. Just stay caffeinated and you'll make it through!

22 tips for writing software documentation users will actually read

Writing software documentation is much like juggling porcupines while walking a tight rope in 50 mile-per-hour winds. Your attention is constantly divided and the situation is always changing. The moment you finalize your work, a new feature appears in the software, and you find yourself scrambling to document it in time for the product release.

So, how do you go about writing technical manuals for software without going insane?

Here are some guidelines you can follow to maintain your sanity when writing software documentation.

• Create and maintain a style guide. Style in technical writing can vary from one product to the next, and you'll save yourself a lot of grief by keeping notes regarding conventions.
• Keep your friends close and your SMEs closer. If you can promote open and frequent communication with developers, writing software documentation will be much easier. You won't be blind-sided as often by changes in the software.
• Install often. Don't waste time writing software documentation for an out-of-date version of the product.
• Make time for testing. Be sure to try out every procedure at least once to verify that the instructions are accurate.
• Talk to the Support staff. You'll be more effective at writing software documentation if you understand the problems users typically experience.
• Use templates. Have a template for each topic type (reference, FAQ, procedure, etc.) and use them for quickly fleshing out new topics. You can find detailed document templates here.
• Invest in your tools. A feature-rich set of technical writing authoring tools will make the process of writing software documentation much smoother. A help authoring tool, such as Adobe RoboHelp or MadCap Flare, and a tool for print documentation, such as Adobe Framemaker, will suffice. Some XML-based authoring tools are capable of producing both printed documentation and help.
• Invest in your skills by learning from others. If you run into problems while writing software documentation, open up the MadCap Flare help or an Adobe RoboHelp manual and see if they've tackled the same situation. Find examples of great technical writing and emulate them.
• Stay organized. Learn to use project management software to track pending tasks and notes. Keep a manila folder for each project and fill it with printed copies of notes and important email messages. This is especially important when writing software documentation for multiple products at once.
• Keep a list of questions for SMEs. Your time with them will be more productive, and they will appreciate your respect for their busy schedules.
• Focus on your help navigation, table of contents, or index. There's no point in writing software documentation that users can't find. Enable full-text search, if possible.
• Prepare use cases, and compare your procedures to those use cases. Does your documentation cover all of the tasks your users need to complete? If not, fill in the missing content.
• Be specific. When writing software documentation you must be particularly clear about tasks the user must complete versus tasks that the software completes automatically. Ambiguous language will leave users scratching their heads or reaching for their telephones to call Support.
• Provide context. Writing software documentation isn't just about telling users what to do. You must also tell them why they would want to complete a task, and explain the desired outcome. This point is particularly important for anyone using a single-sourcing methodology where chunks of content are combined to create the final output. Be sure to provide context to show how those chunks of content are related and create a feeling of continuity.
• Verify that your documentation set is complete. Did you include accurate installation instructions? How about contact information for Customer Support? Does your product warrant a tutorial or interactive training? Writing software documentation often requires producing more than just a printed manual or online help.
• Leverage existing content. If your company provides a knowledgebase or support website, refer to it in your manuals. Use cross-references to guide users through all of the various forms of product documentation in an intelligent manner.
• Use a consistent design for your documentation. Users will adapt to your design and learn more effectively if you present content in a consistent and user-friendly manner.
• Delete unnecessary content. Writing software documentation isn't like writing a novel, and brevity will often result in improved clarity. However, don't leave out important information for the sake of being brief. Use as many words as necessary to accurately explain a concept, and no more.
• Find peer reviewers. Preferably, get another writer and a product developer to review your documentation. They will help sort out any technical inaccuracies, and improve the clarity of your writing.
• Revise often. The great thing about writing software documentation is that you usually have frequent opportunities to deliver updated content. Developers constantly ship newer versions to include the latest features. Take advantage of those updates and ship your latest improvements to the software manuals and help.
• Set some informal deadlines for yourself. Factor in time for documentation reviews, testing, and dealing with troublesome authoring tool issues. One of the difficulties of writing software documentation is the instability of product release schedules. By maintaining your own aggressive deadlines, you'll be more prepared if the company decides to ship the product two weeks earlier than planned.
• Have some fun. Play network games with the developers, or go out for a long lunch with your fellow technical authors. Writing software documentation is hard work. Don't burn yourself out.

I hope these tips for technical writing make the process of writing software documentation a little less painless. If you're as crazy as the rest of us technical writers you might even enjoy it!