Re: [TCP] Software Manual
I include almost all screen shots in the printed (PDF) documentation. Depending on your audience, the user may not have the software application running. So screen shots, in this instance, are essential. A good example is the CIO of a company may be looking at your product to see if it'll solve potential security issues. He or she will be reading your docs on the plane. Without context (screen shots), the docs can be difficult to understand. I do NOT include screen shots in the online help (well, there are a few exceptions such as the main app window, icons, and so on). As far as whether online help can replace printed docs, that depends on your users. In most of my 20 years of doing this (well, OK, 15 with online help), I've found that when we did not include the user's guide, people howled. And so we provided both online and print (PDF) docs. Generally, the help will install with the app while the UG can be downloaded from the Web site or be installed. Another thing to note... there is some information that is irrelvante in online help but is required in print. Information such as how to install the product, for example. So if you do not have, at the least, a separate installation guide, you're actually gonna confuse your users. Do they need to install the app to find out how to install it? So, my general rule of thumb is: 1. Printed documentation includes installation; includes screen shots; does not include c-s help 2. Online help includes c-s help; does not include installation; does not include screen shots YMMV. Natch. ...sue On 7/16/07, Johnson, Joyce <[EMAIL PROTECTED]> wrote: > > > Hi All - > > What should be included in a software manual? > > This may seem like a simple question, but a colleague of mine has a very > different opinion than mine on exactly what the contents of a software > manual should include, so I'm asking the experts. > > How do you feel about screen captures in a software manual? Are they > essential or can you do without them? > > Do you think online help can replace a software manual? > > Thanks for your help! > Joyce > > > > Joyce Johnson > Lead Technical Writer > AmerisourceBergen Solutions Group > 875 Woodlands Parkway > Vernon Hills, IL 60061 > 847/808-5875 > > __ > > Author Help files and create printed documentation with Doc-To-Help. > New release adds Team Authoring Support, enhanced Web-based help > technology and PDF output. Learn more at www.doctohelp.com/tcp. > > > Interactive 3D Documentation > Parts catalogs, animated instructions, and more. www.i3deverywhere.com > ___ > > Technical Communication Professionals > > Post a message to the list: email [EMAIL PROTECTED] > > Subscribe, unsubscribe, archives, account options, list info: > http://techcommpros.com/mailman/listinfo/tcp_techcommpros.com > Subscribe (email): send a blank message to [EMAIL PROTECTED] > Unsubscribe (email): send a blank message to > [EMAIL PROTECTED] > > Need help? Contact [EMAIL PROTECTED] > > Get the TCP whole experience! http://www.techcommpros.com > __ Author Help files and create printed documentation with Doc-To-Help. New release adds Team Authoring Support, enhanced Web-based help technology and PDF output. Learn more at www.doctohelp.com/tcp. Interactive 3D Documentation Parts catalogs, animated instructions, and more. www.i3deverywhere.com ___ Technical Communication Professionals Post a message to the list: email [EMAIL PROTECTED] Subscribe, unsubscribe, archives, account options, list info: http://techcommpros.com/mailman/listinfo/tcp_techcommpros.com Subscribe (email): send a blank message to [EMAIL PROTECTED] Unsubscribe (email): send a blank message to [EMAIL PROTECTED] Need help? Contact [EMAIL PROTECTED] Get the TCP whole experience! http://www.techcommpros.com
Re: [TCP] Software Manual
It depends. How complex is the software? How complex does the user need to be? Etc. For example, software needs installing and using. Should these be documented in the same manual? Is this software used by pHD geneticists in their search for a cancer cure? If so, do we need to document algorithms, formulae, approaches, etc? Where should that go? Does the software have a variety of complex engineering uses such that tutorials or lessons would be a significant benefit? Where do those go? Is this veteran software with known issues such that a troubleshooting section is available? Or, is this a very small and simple VBA application or game that doesn't do a heckuva lot? And so on and so forth ad infinitum. Cheers, Sean P.S. In general, I include screen captures in the printed docs when they clarify a set of instructions, to help visual learners. The screen captures must reflect what the software looks like, what the document is on about, and realistic settings that make sense. In general, I avoid putting screen captures in the online help because I assume the user already has the software open and doesn't need a picture of the dialog box they are already looking at and because graphics add size. -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Johnson, Joyce Sent: Monday, July 16, 2007 6:13 PM To: tcp@techcommpros.com Subject: [TCP] Software Manual Hi All - What should be included in a software manual? This may seem like a simple question, but a colleague of mine has a very different opinion than mine on exactly what the contents of a software manual should include, so I'm asking the experts. How do you feel about screen captures in a software manual? Are they essential or can you do without them? Do you think online help can replace a software manual? Thanks for your help! DISCLAIMER: Important Notice * This e-mail may contain information that is confidential, privileged or otherwise protected from disclosure. If you are not an intended recipient of this e-mail, do not duplicate or redistribute it by any means. Please delete it and any attachments and notify the sender that you have received it in error. Unintended recipients are prohibited from taking action on the basis of information in this e-mail.E-mail messages may contain computer viruses or other defects, may not be accurately replicated on other systems, or may be intercepted, deleted or interfered with without the knowledge of the sender or the intended recipient. If you are not comfortable with the risks associated with e-mail messages, you may decide not to use e-mail to communicate with IPC. IPC reserves the right, to the extent and under circumstances permitted by applicable law, to retain, monitor and intercept e-mail messages to and from its systems. __ Author Help files and create printed documentation with Doc-To-Help. New release adds Team Authoring Support, enhanced Web-based help technology and PDF output. Learn more at www.doctohelp.com/tcp. Interactive 3D Documentation Parts catalogs, animated instructions, and more. www.i3deverywhere.com ___ Technical Communication Professionals Post a message to the list: email [EMAIL PROTECTED] Subscribe, unsubscribe, archives, account options, list info: http://techcommpros.com/mailman/listinfo/tcp_techcommpros.com Subscribe (email): send a blank message to [EMAIL PROTECTED] Unsubscribe (email): send a blank message to [EMAIL PROTECTED] Need help? Contact [EMAIL PROTECTED] Get the TCP whole experience! http://www.techcommpros.com
Re: [TCP] Software Manual
> How do you feel about screen captures in a software manual? Are they essential or can you do without them? > Do you think online help can replace a software manual? The answer to both questions is: it depends. What is your product? Who is your audience? What do they need? I would not put out a software manual with no screenshots. Screenshots are essential for novice users, and helpful for non-English-speakers (or just the functionally illiterate). Online help can replace a software manual for some people, but not for all. Well-written online help is much better than a manual, but not everyone will use it. YMMV. Diane Evans Requirements Analyst ASQ CSQE Rosetta Inpharmatics 206-802-6560 -- Notice: This e-mail message, together with any attachments, contains information of Merck & Co., Inc. (One Merck Drive, Whitehouse Station, New Jersey, USA 08889), and/or its affiliates (which may be known outside the United States as Merck Frosst, Merck Sharp & Dohme or MSD and in Japan, as Banyu - direct contact information for affiliates is available at http://www.merck.com/contact/contacts.html) that may be confidential, proprietary copyrighted and/or legally privileged. It is intended solely for the use of the individual or entity named on this message. If you are not the intended recipient, and have received this message in error, please notify us immediately by reply e-mail and then delete it from your system. -- __ Author Help files and create printed documentation with Doc-To-Help. New release adds Team Authoring Support, enhanced Web-based help technology and PDF output. Learn more at www.doctohelp.com/tcp. Interactive 3D Documentation Parts catalogs, animated instructions, and more. www.i3deverywhere.com ___ Technical Communication Professionals Post a message to the list: email [EMAIL PROTECTED] Subscribe, unsubscribe, archives, account options, list info: http://techcommpros.com/mailman/listinfo/tcp_techcommpros.com Subscribe (email): send a blank message to [EMAIL PROTECTED] Unsubscribe (email): send a blank message to [EMAIL PROTECTED] Need help? Contact [EMAIL PROTECTED] Get the TCP whole experience! http://www.techcommpros.com
[TCP] Software Manual
Hi All - What should be included in a software manual? This may seem like a simple question, but a colleague of mine has a very different opinion than mine on exactly what the contents of a software manual should include, so I'm asking the experts. How do you feel about screen captures in a software manual? Are they essential or can you do without them? Do you think online help can replace a software manual? Thanks for your help! Joyce Joyce Johnson Lead Technical Writer AmerisourceBergen Solutions Group 875 Woodlands Parkway Vernon Hills, IL 60061 847/808-5875 __ Author Help files and create printed documentation with Doc-To-Help. New release adds Team Authoring Support, enhanced Web-based help technology and PDF output. Learn more at www.doctohelp.com/tcp. Interactive 3D Documentation Parts catalogs, animated instructions, and more. www.i3deverywhere.com ___ Technical Communication Professionals Post a message to the list: email [EMAIL PROTECTED] Subscribe, unsubscribe, archives, account options, list info: http://techcommpros.com/mailman/listinfo/tcp_techcommpros.com Subscribe (email): send a blank message to [EMAIL PROTECTED] Unsubscribe (email): send a blank message to [EMAIL PROTECTED] Need help? Contact [EMAIL PROTECTED] Get the TCP whole experience! http://www.techcommpros.com
