5 Tips for Writing a Software User Manual

I’ve had the opportunity to take part in many projects, some academic and some at work. In each place I learnt standards for working with these software user manuals, which weren’t the same; I had to adapt my own style to the one I was required to use. Many times I had to pick manuals to revise that were made by different people and some of them were really a disaster, with inconsistencies and poor redactions and explanations.

Here are five guidelines you could use the next time you need to work on a software user manual.

 

  1. Write an outline for the manual.

You should start by dividing the software manual into introduction, menus and submenus, toolbars and every other section or tool group the software would have. Remember that it should start by stating the purpose and requirements of the software, followed by the installation procedure. Also include some common tasks, advanced functions, and a F.A.Q. section.

 

  1. Create and maintain a style guide.

The software manual should have writing and design standards that would always need to be followed with no exceptions. If it is done like this, the maintenance and creation process of the manual would be easier; users would also find it easier to understand.

 

  1. Use active voice.

Even though you may have not thought about that, it is easier for the reader to understand if the manual directly gives him orders and instructions. In passive voice, the subject is unknown, which may confuse the reader.

 

  1. Use graphics.

It is easier to understand a manual with screenshots of the software rather than looking for each option or button while reading the manual. There is a saying “An image is worth more than a thousand words.” It reflects how important is the visual aid when you try to explain something new to someone. It can also simplify and reduce the text.

 

  1. Write clear instructions.

Even though it is obvious, some people forget that the user manual is a document for the user to understand the software, not for your supervisor who already knows everything related to the software. These instructions should use numbered lists and each number should just include a step.

 

Follow these 5 easy tips and you will notice a really big change on the feedback of your work.

 

Nestor Mancilla V.

Advertisements

2 thoughts on “5 Tips for Writing a Software User Manual

  1. You’ve summarized the process quite succinctly here.

    I have a few editing comments I hope you’ll take in the spirit in which they are given: to educate not to criticize.

    “In each place I learnt standards for working with these software user manuals, which weren’t the same; so I had to adapt my own style to the one I was required to use.” –> The semi-colon should be a comma because you’re not connecting two complete sentences which is what a semi-colon used for. If you omitted the “so”, the semi-colon would be appropriate.

    “… with inconsistencies and a poor redaction and explanations.” –> The article “a” indicates that a single item will follow when in fact two do. And since “explanations” is plural, “redaction” should be as well.

    “You should start by dividing the software in introduction, menus and submenus, toolbars and …” –> You don’t divide the software; you divide the manual “into” (not “in”) sections.

    There should be a period after the Q in F.A.Q.

    “The software should have writing and design standards…” –> Again, the software doesn’t have standards; the manual does.

    ” If it is done like this, the maintenance and creating process…” –> “Creating” should be “creation”.

    The fifth item heading is missing a period.

Comments are closed.