PDA

View Full Version : User manual



ssb
05-08-2005, 06:26 AM
If anyone has any suggestions on writing a user manual, I'd appreciate hearing them. I'm just starting my writing business and have been working with the Small Business Development Center at a local university on various business startup topics; they referred another new small business person to me to write the user manual for his new product - a driver fatigue detector.

I hope to meet with the inventor soon and learn more about what he is looking for. I'm fairly comfortable with the actual writing, but don't know what to charge. I'm so excited about having a potential client before I was actually marketing, I'd almost be willing to do it pro bono to build a track record and have a good reference. Any suggestions?

Also, I don't know yet if he just wants me to do the content or if he's looking for an actual finished product. Any recommendations on what to look for if I have to coordinate work with a print shop for such a project?

Any other thoughts or comments are appreciated.

Thanks in advance.
Sally

wardmclark
05-08-2005, 11:49 PM
First, get a complete handle on what he expects.

I do rather a lot of user manuals/instructions. I use a digital camera and build a lot of illustrations into instructions; in this instance a picture really is worth a thousand words. Most of my instructions are for medical devices; I write both end-user instructions and manufacturing and quality instructions for the manufacturers.

A couple of tips:

1) Talk to him about the intended use and users, and write accordingly. Instructions for the general public have to be written in very clear, concise and intuitive language; sadly, literacy today isn't all it should be. If the intended users of this product are professionals - i.e. health care pros, engineers, people like that - you won't have to worry about the KISS principle so much.

2) Printers - if they expect a final product from you ready to send to the printer, find out what printer they're using (or if it's up to you to find one, find a good one before you start.) Talk to the printer and find out what formats they can use. Any graphics they'll probably want sent seperately, in 300dpi form, usually a .tif or .png file. Many printers won't work with a Word file - they'll want the file in Adobe Pagemaker or Illustrator. Most can work with a pdf file, though, which you can produce from your Word document. That's a capacity that you should have in this business anyway.

Hope this helps. If there's anything else, please ask.

And good luck!

ssb
05-09-2005, 04:57 AM
Ward,

Thank you so much for the great information. Definitely good points I can use. Will let you know how things go.

Thanks again.
Sally

Good Word
05-10-2005, 06:36 AM
Sally,

Ditto what Ward said, and I would be careful about the printer end of it--typically the writer's finished product is the text. If they want to pay you hourly to help find and coordinate with a printer, that's one thing, but you don't want to get into the position of being responsible for the final printed product, paying a printer, etc. What if the binding is wrong? Should that come out of your check? NO. It's best to deliver the writing in the agreed upon format, and the company takes it from there--the best way to go, IMHO, unless you are a full time employee. Your forte is the content, and you'd be happy to help, but...

As far as what to charge, consider the standard rate in your area, and make sure you get paid as you go, or as much in advance as you can, if possible. Don't wait to get paid until the end--what if the product isn't ready for release and you don't really know when the end is? You don't want to wait forever to get paid. Can you work out getting paid hourly and bill them every two weeks? Or perhaps give a broad estimate (you never know how long it's really going to take until you finish-- on my last project I estimated between 40-80 hours) and get paid in three installments--beginning, middle and end?

If this company is a one-man-show, you want to make sure there really is money to pay people. It's not rude to ask, at the right time, "Wow this is so interesting and must have taken a lot of resources to get off the ground--are you funded by an investment company?" --Or something similar.

Hope this is helpful.

Lisa

ssb
05-10-2005, 06:47 AM
Lisa,

Thank you for the excellent advice. I have a feeling it is a one-man show, so the funding is a good consideration. You & Ward are definitely helping me avoid some errors and be better prepared. Thank you!!!

Sally

Frumious B
05-10-2005, 01:16 PM
Ward and Good Word have given excellent advice. One other thing to ask about before you start is the availability of the Subject Matter Expert (SME). Unless you are already expert at the product, you will need to have access to a person (or team) who knows the product inside out. This person needs to be available; it's no good having an SME who is never around!

My SMEs are my lifeline!

wardmclark
05-11-2005, 02:43 AM
Sally,

Ditto what Ward said, and I would be careful about the printer end of it--typically the writer's finished product is the text. If they want to pay you hourly to help find and coordinate with a printer, that's one thing, but you don't want to get into the position of being responsible for the final printed product, paying a printer, etc. What if the binding is wrong? Should that come out of your check? NO. It's best to deliver the writing in the agreed upon format, and the company takes it from there--the best way to go, IMHO, unless you are a full time employee. Your forte is the content, and you'd be happy to help, but...Lisa

Yeah, but... :)

You're right in that a writer should be responsible primarily for the content.

But I - and this is just me - do a lot more than that. Mostly for the following reasons:

1) Diversification is good for a business. Being able to provide more services is better than being able to provide fewer services.
2) When a customer asks "can you handle X," I prefer to be able to say "yes," instead of, "no, I don't do that." It's another thing I can add to the invoice.

So, I've made a point of learning about different aspects of things that tie in to copywriting.

Mind you, that's just me, and I'm a workaholic. I've already mentioned that I own two other businesses besides the copywriting business, and I work 70-80 hours a week. YMMV. ;)

Good Word
05-13-2005, 07:29 AM
Ward, I understand where you are coming from. It's obvious that you have a lot of experience, but I think it depends upon the situation. When I worked for a big software company, I worked with plenty of printers too, and have a bit as a consultant. But for Sally, just getting started and having a client with perhaps not much funding/probably looking to cut corners, I wouldn't recommend being responsible for producing the finished product, particularly if it might mean taking a financial hit if there are errors.

wardmclark
05-14-2005, 02:45 AM
Ward, I understand where you are coming from. It's obvious that you have a lot of experience, but I think it depends upon the situation. When I worked for a big software company, I worked with plenty of printers too, and have a bit as a consultant. But for Sally, just getting started and having a client with perhaps not much funding/probably looking to cut corners, I wouldn't recommend being responsible for producing the finished product, particularly if it might mean taking a financial hit if there are errors.

No argument at all. You'll notice I said "...and this is just me." ;)

ssb
05-17-2005, 02:51 PM
Just to give you a quick update... turns out this client is more established than I thought from initial phone call. They have a graphic artist and printer they will use. So I only have to be concerned about the text.

Another question, if you're so inclined.... I have some concern about liability. Given the product is a monitor for driver fatigue, I don't want any issue about someone finding their way back to me if they're in an accident because they fell asleep even using the monitor and blame it on the installation instructions. My client has said they will be including some legal disclaimer that use of the product doesn't guarantee they won't fall asleep - for example, if they try to drive on one hour sleep, chances of an accident are still high; or if they ignore the warnings from the monitor and keep driving, etc. Should I ask my client for some liability release paper (or what would you call it?) and have my lawyer review it? Or should I be presenting something for them to sign that my lawyer drafted?

Thanks again.
Sally

pconsidine
06-03-2005, 12:35 AM
And here I was just about to offer my book production assistance.

Well, the offer still goes. And for anyone else who has questions about production matter, too. What the heck.

:)

As far as a release form, I don't know if it's standard practice or not, but it sounds like an incredibly good idea. I would think that the ultimate liability would fall to whoever at the client company is responsible for approving the final text, but covering your butt is always a good idea, as I see it.

Just my 2.

my1stname
06-04-2005, 02:57 AM
Hi. I've been looking all over for a decent technical writing discussion group and this is the best site!

BACKGROUND: I just started an internship as a technical document writer for a fast-growing software start-up with lots of capital, in the Washington, DC area. (So if you guys help me, I might be able to bring you in!) I fell into having two years experience in the software development life cycle. I then went back to school for formal computer training. One of my courses was technical writing, where I wrote a user's manual for software I created in a systems analysis class. Now, I'm trying to get back into the work force.

DESKTOP PUBLISHING SOFTWARE: The company I work for has what is basically a reference written in Word. I was under the impression that a decent document would be written in QuarkXpress or Framemaker. My people know nothing about documentation and I need to educate them, but I need to educate myself first. My boss says that at previous companies, everyone used Word. Well, I'm thinking: of course, because programmers know nothing about writing and usability! And why would he want our company's products to be on a par, rather than better, than other companies' products? I need some articles or statistics showing that Word is not professional enough and Quark, Framemaker, or other software (?) is.

ON-LINE HELP: The company's software product doesn't even have on-line help. I'd like to argue that on-line help should be the first priority. Realistically, no one reads user's manuals. Personally, I first check on-line help, then on-line discussion forums, then contact tech support. I never check user's manuals. Most people don't even know where the user's manual is. Does anyone have any articles or stats on this point? I convinced my boss to buy me Robohelp so I can keep its requirements in mind when writing for hard copy, so there would be a seamless transition, but have not yet approached him about changing the priorities.

USER'S MANUAL: The only way to make their user's guide usable is to organize it well, and pretty it up. If we do concentrate first on the hard-copy user's manual, I think we should focus on features, FAQs, and troubleshooting. The remainder of the reference should be organized into scenarios. But I don't have enough articles or stats to back up my thinking. Anyone agree/disagree or have tips? Like I said, you might get a job out of this -- seriously, new people are joining every 2-3 days!

KNOWLEDGE BASE: My other concern is how user's guide information interacts with knowledge bases for tech support. (The tech support manager person was hired the same day I was so I'm in a position to influence her!) Does anyone have any experience in this area?

I'm sure responses to these concerns will benefit our colleagues. Thanks, guys!

pianoman5
06-07-2005, 08:39 AM
I've just scored a gig to review and refresh some established (software) user documentation, including streamlining the processes by which updates are managed and applied, so I've recently been researching the whole area to update my knowledge.

DTP - There's still some debate about which products are the most suitable, and as you might expect, some writers have entrenched positions on the matter. Those who have been doing it for years swear by products like FrameMaker, which is still a popular option. The argument for products of this type is that they are true DTP solutions built for managing text and illustrations in bulk, and although they are harder to learn initially, they unquestionably deliver the required functionality. The downside in a collaborative environment is that the tech writer may be the only one who has it on his machine and knows it, so it results in a bit of double handling etc.

The argument against Word used to be that it is only a Word Processor with aspirations, and that it is not so good at manipulating a mixture of images and text. Also, older versions on less powerful PC's were very poor at handling large documents, as manuals often tend to be. Those arguments appear to have largely evaporated with newer versions of Word and the availability of beefy processors with plenty of memory.

My take is that Word is now a perfectly acceptable alternative, and the fact that almost everyone has it (or can at least handle a .doc document with an alternative) adds to its appeal where text needs to be gathered from multiple sources. Most companies output to pdf for the finished product for easy download and guaranteed format/printability.

ONLINE HELP - This is very much the name of the game these days for software related documentation. But there is still a (usually mandatory) requirement for hard copy, so the ideal situation is where the two can be developed and maintained side by side. Some products have emerged that are called 'single source' in that their aim is to capture once and publish to many alternative formats. Most will accept input directly from word and publish in doc, pdf, winhelp, html help and xml formats etc. I will probably be investigating some of these alternatives in the coming weeks. The market leader seems to be WebWorks Publisher for Word (www.webworks.com (http://www.webworks.com/)).

USER MANUAL - The key to the success or otherwise of all documentation is that it should be pitched appropriately to the class of user it targets. One of the commonest complaints about user documentation is that it does not address the needs of the 'dumb' user. A lot of documentation is prepared by technical SME's, often the people that develop the product, then refined by somebody who is one step removed from the front line but still technically oriented. The critical final step (unlikely to be argued about by anyone on this board!) of having it reviewed and polished up by a technical writer with a dumb third party user perspective is often omitted.

Every product will have different requirements of course, but in general it's accepted that most users are not concerned with 'how' something works, only how they can use it with the minimum of fuss. This generally implies including a number of worked examples and illustrations to guide them without making any assumptions about how much they know.

Ideally, documentation of complex products should come in three flavours - complete rookie, intermediate and expert. But that is usually impracticable, so the compromise version usually fails the rookie while patronising the expert and not giving him enough detail for his purposes. Most s/w products, however, usually come with both a user's guide and a system administrator's guide, so that addresses the problem to some extent.

KNOWLEDGE BASE/USER GUIDE - Not sure exactly what you mean here, but I do have a view about how knowledge bases and online user guides can interact. The availability these days of the HTML/web hypertext environment means that basic online help can be augmented tremendously by hyperlinks that connect the user to relevant deeper information, troubleshooting tips, reported problems and the like. If one could make the assumption that every possible user was connected to the internet, online help could be linked to the originating company's public web site and automatically have up-to-date knowledge base info available. As it is, while we're close to that nirvana it's probably not a safe assumption, so an alternative would be to make a set of downloadable html-based support files available for users to access on their local network, which could be refreshed periodically.

Hope this helps.

Susan in Houston
06-09-2005, 11:20 PM
I did several user manuals for proprietary software at a large company. The most important point to remember is that you're writing for someone who knows nothing about the product. Start off at ground zero; with the most elementary information. Use lots of screen shots (which are easy to cut and paste into Word, or whatever you're using) and tell them where to go on each shot. We always did chapters based on accomplishing something specific--i.e. "How to pay an invoice" and then walked them through that from the first page after logon. Would love to work on this if I'm what you're interested in.




Hi. I've been looking all over for a decent technical writing discussion group and this is the best site!

BACKGROUND: I just started an internship as a technical document writer for a fast-growing software start-up with lots of capital, in the Washington, DC area. (So if you guys help me, I might be able to bring you in!) I fell into having two years experience in the software development life cycle. I then went back to school for formal computer training. One of my courses was technical writing, where I wrote a user's manual for software I created in a systems analysis class. Now, I'm trying to get back into the work force.

DESKTOP PUBLISHING SOFTWARE: The company I work for has what is basically a reference written in Word. I was under the impression that a decent document would be written in QuarkXpress or Framemaker. My people know nothing about documentation and I need to educate them, but I need to educate myself first. My boss says that at previous companies, everyone used Word. Well, I'm thinking: of course, because programmers know nothing about writing and usability! And why would he want our company's products to be on a par, rather than better, than other companies' products? I need some articles or statistics showing that Word is not professional enough and Quark, Framemaker, or other software (?) is.

ON-LINE HELP: The company's software product doesn't even have on-line help. I'd like to argue that on-line help should be the first priority. Realistically, no one reads user's manuals. Personally, I first check on-line help, then on-line discussion forums, then contact tech support. I never check user's manuals. Most people don't even know where the user's manual is. Does anyone have any articles or stats on this point? I convinced my boss to buy me Robohelp so I can keep its requirements in mind when writing for hard copy, so there would be a seamless transition, but have not yet approached him about changing the priorities.

USER'S MANUAL: The only way to make their user's guide usable is to organize it well, and pretty it up. If we do concentrate first on the hard-copy user's manual, I think we should focus on features, FAQs, and troubleshooting. The remainder of the reference should be organized into scenarios. But I don't have enough articles or stats to back up my thinking. Anyone agree/disagree or have tips? Like I said, you might get a job out of this -- seriously, new people are joining every 2-3 days!

KNOWLEDGE BASE: My other concern is how user's guide information interacts with knowledge bases for tech support. (The tech support manager person was hired the same day I was so I'm in a position to influence her!) Does anyone have any experience in this area?

I'm sure responses to these concerns will benefit our colleagues. Thanks, guys!

Mac H.
07-27-2005, 10:33 AM
If anyone has any suggestions on writing a user manual, I'd appreciate hearing them. ..
Any other thoughts or comments are appreciated.


I've written a few User Manuals/ Installation Guides etc.

One short cut is to browse the web for some similar products and look at their manuals. In your case, if it is some equipment that is installed in the car, a car radio manual might be useful.

Get a few different styles, print them out and show them to the customer, so they can 'choose' the style that they want. For example, are they after an A3 sized booklet, with a combined User Manual/Installation Guide ? Or do they want an extensive workshop/troubleshooting manual that can be put in a ring-binder in the workshop? Having some samples that you can attack with a highlighter pen gets you up and running very quickly.

It will also remind you of sections that NEED to be in the manual but which the inventor hasn't thought of. Like the section on cleaning it. (eg: Cleaning: Use Isopropyl alcohol with ... Abrasive cleansers must be avoided, etc)

These are the kind of sections that nobody thinks of, but are kind of obvious once you see them in the manual.

Another thing to remember is that you'll want a single page summary of the specifications. There will be some standard specifications (temperature, Atmospheric pressure) as well as a few lines on standards compliance. (eg: Complies with IEC-60601/AS 3200).

Sections I often use include:

* Welcome/Introduction
eg: 'Congratulations on choosing a BZ5000, the latest in ...'
* Features
* Setting up / Installing
* Using the ....
* How To ...
* Care and Cleaning
* Troubleshooting
* Warranty
* Service and Spare Parts
* Packing Instructions
* Declaration of Conformity
* Standards Compliance
* Technical Specifications
* Index

In terms of cover, etc, you'll want to leave a section for the distributor's sticker etc. (Which will have somebody else's contact info. Even if they are distributing it themselves, it will give them a chance to change the tech support email address/phone number when they grow, without having to reprint manuals)

Simply printing them out yourself with a crude staple in the middle will give them something to hold in their hands that 'feels' like the finished one, and is a lot easier to mark up than a printed out A4/Letter manuscript that they've just gotto accept will be in a different size.

Anyway, that's just my experience.

Mac.
(PS: A cool graphic on the cover never goes astray - Even on a early draft !)