Five Tips for Writing a User Manual

Technical-Manuals

*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*

A successful user manual provides quick answers to questions that users might have about how to complete tasks. Technical writing focuses on the tasks along with the concepts that support them.

Here are five practical tips on writing user manuals.

Think like a user

You should have a good understanding of your users so you can understand the information they need to know, how they approach each task, and when they might use approaches to tasks that are unexpected.

Use active voice

Sentences that use active voice emphasize the user and are easy to read and understand. In active voice, the subject and verb in the sentence are clear. In passive voice, the subject is unknown and is acted upon by something that is not known or not stated. Passive voice uses verbs that include a form of “to be”.

Focus on the reader

When writing information that involves the reader, such as instructions, pull readers into the document by using “you” to make the content relevant to them.

Compare the two sentences below.

Reader focus: You can choose from one of three options for viewing content in the editor. 

Lack of reader focus: There are three options for viewing content in the editor.

The sentence that uses “you” makes it clear that the reader is the person doing the action.

Write clear instructions

The primary objective of user manuals is to help users complete tasks. Here are some guidelines.

  • Use numbered lists for instructions, unless the instruction includes a single step.
  • Use parallel construction for each step. Typically, you should start each step with an imperative word that provides clear cues.
  • Avoid using a system response as a step. For example, don’t say, “The Info dialog window opens” as a step. Mention the system response at the beginning of the following step (for example, “In the Info dialog window…”.
  • Provide just enough information so that the user can complete a task or understand a concept. Concise content makes it easier to understand concepts and tasks. 

Establish standards

When creating documentation, there will be areas where there may be more than one way to spell a word, refer to an object, caption graphics, punctuate sentences, lay out a page, and organize information. Establish standards by making decisions for users beforehand.

In addition, use an established style guide, such as The Chicago Manual of Style and Microsoft Manual of Style to establish some specific guidelines for your writing project.

Have something to add? Please share it in the comments.

How Technology is Making Us Lazy

lazy-computer

Inspiration for this article came from David Dick at STC’s Notebook.

Technology is making our life much more comfortable, and we are getting lazier.

Here are some of the ways technology is making us lazy:

  • You only visit friends or family on FaceTime or Skype.
  • You wonder where someone is if they don’t answer their cell phone immediately.
  • You buy a new pair of jeans on the Internet.
  • You pay all your bills online.
  • You order food and groceries online.
  • You blame your GPS for sending you to a dead end street.
  • You use Facebook to send holiday cards.
  • Your kids consider Wikipedia a reliable resource for term papers.
  • Family time involves everyone sitting together in the living room playing Candy Crush on their smartphones.
  • You friend and unfriend people on social networks without actually meeting them.
  • You write to your mother by sending text messages.
  • You call your father in the living room from your bedroom because you don’t want to get out of bed.

Have something to add? Please share it in the comments.

 

Which Skill Sets Are Important for a Technical Writer?

techwriting

This article first appeared in Writing Assistance, Inc.

Like any profession, becoming a technical writer requires a mastery of a certain set of skills. When large manuals were the standard in the profession, this skill set involved primarily writing and illustration skills. But today the worlds of communications and technology have evolved dramatically. How has that evolution affected the skill set required for a technical writer?

Writing skills – For a technical writer, writing skills can never be overlooked. The technical writer still needs to write in a clear and concise manner and to be able to convey information appropriately for a variety of audiences.

Technical skills – The technical skill set of a technical writer depends greatly on the subject matter, product, or service that requires documentation. Hardware and software documentation differ in the skills that the technical writer needs to bring to the table. Additionally, pharmaceuticals and other manufacturing industries have specific requirements that translate into knowledge the technical writer must have.

A technical writer asked to document a developer’s guide may need to have a pretty good handle on specific programming languages, while a technical writer tasked with documenting a weapons defense system might need a high degree of engineering comprehension as well as a solid knowledge of government documentation standards.

Tools skills – Of course, a technical writer needs to know his or her way around computer systems, since they are used to produce documentation in a variety of formats. Specific tool knowledge, such as Adobe FrameMaker, MS Word, MadCap Flare, RoboHelp, and even PageMaker and Quark really depends on the tools the organization has come to rely on in order to produce its technical documentation.

However, technical writers are accustomed to learning – it’s really what they do, and most are capable of learning a new tool quickly and efficiently.

Interviewing and listening skills – Technical writers need to know how to ask questions. They also need to know who is the best person to approach and they need to have a feel for the varying personalities and preferences of the people – the subject matter experts, or SMEs – in order to know how best to approach them.

Once the technical writer has found the appropriate SME to approach, strong listening skills will be required to capture the information necessary and to know which follow-up questions need to be answered.

Design skills – An appreciation for the visual can be an important part of the skill set of a technical writer. Even the earliest technical documents didn’t consist of just the written word.

To a growing extent the technical writer needs an appreciation for graphics and formatting as well as illustration skills. Depending on the needs of the organization, these skills may only need to be rudimentary or they may need to be very advanced.

Usability and testing skills – A technical writer may also be asked to take an active role in usability and testing. Even if not asked to take a role, the technical writer knows that validation of the documentation is important – the confirmation that the product works the way it is documented to work. In some organizations, the technical writer is an important part of the User Experience team.

These skills are just a small part of what a technical writer brings to the table. The skill sets of a technical writer vary widely, depending on the technical writer’s experience and educational background.

Have something to add? Please share it in the comments.