How to Begin Writing an In-House Software User Manual

How to Begin Writing an In-House Software User Manual

Simple oil change on a BMW 325i. Inspection reset instructions at the end of the video. Took about 45 minutes.

User Manual Guide

Gather Information

Diving head first into a writing project before you know the essentials makes writing the manual difficult and could possibly delay deadlines. Steps taken at the beginning of the project are just as important as the actual writing of the manual. Before the writing can begin, there are many factors you need to know so that the project will flow smoothly.

This section discusses the things you need to do to learn all the particulars and issues of the project before you begin the writing process.

Schedule a Meeting

First, schedule a kick-off meeting that involves everyone who is involved in the project. Take plenty of paper and a pen. Write down any observations or statements that the attendees make. In addition, make a list of the following:
•Company's physical location (especially if the project participants are located in separate divisions)
•Audience for the manual (Will the readers be mid-level employees, managers, corporate personnel, or other?)
•Subject Matter Expert (SME) names
•Deadline of the project

It is also necessary that you know who is in total charge of the overall project in the event that a disputed issue arises during the writing of the manual.

Study the Software

Before you start writing the manual, get access to the software you will be writing about.

If you have never used or seen the software before, this is a good way to get an insight into how the users will see it for the first time. Play with the software to get familiar with its features and functions. Go from screen to screen, and pay close attention to tabs, fields, buttons, options, and any other information on the screen. Also note any fields that are automatically populated by the software.

While going through the software, jot down words or actions that could be used as headings or subheadings in the manual. This will help you tremendously when you get ready to create the outline.

If the company has any written material on the software, whether it is completed or sketchy notes, review the information. Make notes on what needs to be written more clearly or in more detail.

Next, make a list of questions for the SMEs. Is something confusing to you? If so, it would also be confusing to the reader. Should some of the options on a particular screen be rearranged to make logical sense? Should a cancel option be included on a screen in case the user makes an error and wants to go back to the previous screen or start over altogether? Be sure to write down ALL questions that occur to you, no matter how irrelevant you think they may be.

Prepare for the Interview

Now that you have familiarized yourself with the software, the next step is to interview the SME(s). An SME could be the person who actually invented the software or the expert who has used the software for quite some time. Or is could be both.

Before beginning the interview, add the following information to your list of SMEs names:
• Office and cell phone numbers
• Email addresses
• Physical location(s) if at a different location
• Section(s) of the software the SME has the most experience in
• SME's work schedule for the time it will take to complete the manual so that you will know if they have planned a vacation or time off during the project or if they have a business trip scheduled.

Keep the above information on hand at all times during the writing process. Sometimes you need answers or guidance, and it cannot wait. If you have difficulty getting help, insert a placeholder in the document with the question or a description of the problem and who is responsible for providing the information. Highlight the placeholder so that it draws your attention each time you review the manual. Make every attempt to get the information as soon as possible so that it does not prevent you from meeting the project's deadline.

If possible, get the name of a backup SME in case the first SME is unavailable at a critical time when you are writing the manual. Email the backup SME's answers or suggestions to the original SME so that both parties are in agreement of the information provided.

Interview the SME

Now it is time to actually sit down and interview the SME(s). Sit at a desk or table with the software running on a computer. This helps you to show the SME the screen or action in question, and it helps the SME explain the answer more thoroughly.

After interviewing all the SMEs involved, type your notes in a separate document. Group the notes that are related to one another. If you cannot remember something the SME said or pointed out in the software, do not be afraid to go back and ask again. On occasion, communication is misinterpreted or misunderstood.

It is perfectly acceptable for you to ask a question more than once. After all, you did not write the software. You are learning it just as the users will learn it. If a concept is difficult for you to understand the first time it is explained to you, it might take some users several times to get it right. In that case, a different approach to the subject may be necessary.