Writing Software User Manual in MS Word

I'm going to write a software (written for Windows) user manual for a software that we've written for our client. The manual needs to be as detailed as possible. I'm going to use MS Word 2010 to write the manual.

I plan to put a lot of screenshots of various windows of the software and annotate on the screenshots. The page size needs to be A4 so that users can also easily take printouts. The problem is, if I take full screen (the software takes the whole screen, except the taskbar) screenshots and try to fit them on A4 size paper, many texts on the windows as well as annotations may be hardly readable.

To make things easier for the users, I'm thinking of putting links on the manual, and embed screenshots in the word. Clicking the link should open the linked embedded image in full screen. Users should be able to go back to manual with or without closing the image.

The problem is, I don't know if this can be done in Word. Is it possible? If not, is there any alternative/better approach?

Donotalo

Posted 2012-11-29T04:50:08.750

Reputation: 1 049

3> I'm going to use MS Word 2010 for writing the manual — that's where the issues start. There are various other programs for creating technical documentation such as FrameMaker, LaTeX, etc which would deal way better with navigation and structure. As for the "pop up images", I'm not sure how that could be achieved though.. – slhck – 2012-11-29T04:56:47.537

@slhck: our client will accept doc files, and if we push may be pdf. besides, unfortunately, there is no expertise available right now to work on the software you mentioned. – Donotalo – 2012-11-30T05:36:50.720

Answers

I've actually written a lot of technical documentation in Word. It's not the tool I'd choose if I had a free choice, but tech writers often don't.

What you're talking about it certainly doable — but I can only say that when I make some assumptions about how you're going to deliver the manual. If you're planning to deliver the manual as a PDF and put those external screenshots on the web, then yeah, it's doable. Word 2010 lets you embed URL links anywhere in your document. These links are preserved when you save the file as PDF.

I think you're making one bad assumption here, and that is that a screenshot has to show the entire application window. I often capture only enough of the window so that the user can identify the same thing on their own monitor.

You didn't ask about software, but I'll recommend some anyway. On Windows, SnagIt is the indispensable screen shot tool. It's always been good, and it's only gotten better over the years. The capture mechanism keeps getting more and more powerful and easy to use, and now the damn thing comes with a pretty good graphics editor, just the thing for drawing those callouts.

Isaac Rabinovitch

Posted 2012-11-29T04:50:08.750

Reputation: 2 645

1thanks Isaac. unfortunately, uploading the images to web isn't a solution as end users may not have internet connection at all. – Donotalo – 2012-11-30T05:41:19.137

@Donotalo Then how are you planning to deliver them? – Isaac Rabinovitch – 2012-11-30T18:01:15.223

1we'll deliver the manual to our client. not sure how our client will deliver them to end users. most likely through LAN, or of end users outside LAN, may be there are some admins, who will receive the docs via email. the admins will somehow copy the docs to user pcs. – Donotalo – 2012-12-02T01:23:43.257

@Donotalo So you're saying you don't know what form the manual will be in when it's finally read? Then you have no control over the final appearance of the manual and there is no way anybody can answer your question. – Isaac Rabinovitch – 2012-12-02T01:31:46.383

1i'm sorry but when did i say that? the doc needs to be in word document format (.doc). may be in .pdf, but i'm not sure. whatever it is, i need to write it in MS Word. – Donotalo – 2012-12-02T09:57:13.563

Alternative approach (which may or may not be feasible based on your new software) is to play around with the images a bit.

Do they need a full screenshot or are you trying to draw attention to a particular detail?
If not, perhaps you can crop the image down a bit.
Could you reduce the resolution of your computer to take a screenshot with less wasted space?
Instead of taking the screenshot at 1920x1080, try taking it at 1024x768 (or a slightly higher/lower resolution depending on your preferences. That way, instead of having to scale the image down a lot to fit the page, it would only need a slight scale down (or up even) making it more readable.

Robotnik

Posted 2012-11-29T04:50:08.750

Reputation: 2 280