|
Manuals
Would those of you who have written manuals for your products please share some tips as to how you produced it. Not how you wrote it, but how you had it printed. Did you use QuarkXPress or Pagemaker then take it to say Kinkos, or did you simply use MS-Word? Any other tips for writing or publishing a manual?
Manual Person
Monday, October 27, 2003
Yeah - don't.
Just publish the thing to pdf and throw it on the CD. IMHO manuals are a waste of paper (and I print a LOT of stuff, including some manuals). Most manuals I get with software go either in the trash or on the shelf.
Philo
Philo
Monday, October 27, 2003
_Crappy_ manuals are a waste of paper. The real issue here is: Why are so many manuals so crappy?
The advantage of a manual ought to be that it can highlight features you wouldn't have discovered on your own, or go more in-depth on features you do know about. When a manual doesn't do this kind of thing, then it certainly is a waste of paper.
Kyralessa
Monday, October 27, 2003
I've used Philo's technique with the best success. Software changes too quickly for printed manuals to be practical. I like PDFs (which I generate through LaTeX), but HTML works really well for me too.
I'm also a fan of making manuals available online. The manuals that I use the most also happen to be available online through the publisher's web site.
http://www.lazarusid.com/download/imagemanager/manual.html is my own answer to this. http://www.boutell.com/cgic/ is a great example of the web site promoting the product and the manual are the same document. This is the best, because the quality of the manual and the interface was a major selling point on this software.
Clay Dowling
Monday, October 27, 2003
As an end user I *really * dislike PDF manuals, and I use manuals quite a lot (particularly for statistical and mathematical software, e.g., for Splus). They are hard on my eyes and make browsing and looking for specific content quite hard. Yes, I can search the file, but I could also look at the index of a well written manual. I can not take the PDF in the bus without taking my computer (or PDA if I had one). The 'book' UI still is far superior to any lousy PDF file.
uncronopio
Monday, October 27, 2003
I also find manuals in PDF to be incredibly annoying -- if for no other reason (and there are plenty of other reasons, I'm just listing the biggest two annoyances) because (a) I like to use my mouse wheel to scroll, and (b) the load/refresh times are way too noticeable.
Sam Livingston-Gray
Monday, October 27, 2003
What I really find irritating are .pdf manuals automatically created from .html files, so that they have loads of blank, or scarcely used pages.
If you're going to use .pdf files for your software manual print them out in both A4 and Letter and see how they look.
You need to provide both a ,pdf manual for printing, and a html one for looking at on screen. Spend time checking the very different formatting required for both, and remember to check that the .pdf file looks fine in black and white because plenty of people are going to be using a laser printer.
I find I use maybe one manual in three or one in four, so it is probably not worth a developers while producing the printed copy himself, unless the software is high priced and he wants to impress the client.
Stephen Jones
Monday, October 27, 2003
As for "how to produce" I'd say look at a help content package that manages content and publishes to PDF and HTML (and HTML Help and winhelp and ...)
I use Help & Manual, but there are others.
Philo
Philo
Monday, October 27, 2003
I personally think PDF manuals are the worst variety. I tend to prefer CHM or HTML formats.
I don't like printed manuals for small software packages, but for larger applications I often feel the need to just browse through a good ol' printed version. Plus it's a lot easier to dog-ear.
NC
Monday, October 27, 2003
I readily use both printed and electronic formats for manuals, depending on the situation. Though I do agree that pdf's are often inconvenient to read, I'm glad to have them as an option and do use them. I like hard copy because of portability, readability, and random-access -- it's far easier (for me, at least) to browse a physical manual for information than to have to second-guess WTF the vendor calls the particular feature or function I'm interested in learning about to make their friggin' search function find what I want. I like electronic format because of portability (different situations than hardcopy) and size; I've uploaded my copy of O'Reilly's Perl CD to each machine at work and home that I use regularly (it's all html). Very convenient that way.
Before you worry about how to produce the manual, take heed to the comments earlier about "crappy" manuals. Very important advice.
Too often the documentation group gets left out of the project until too late, and they don't have sufficient time to do their jobs well. So take care to involve the doc team early-on, then update them frequently throughout the current release's development. I used to own the entire development support and delivery mechanism (qa, docs, homologation, lab services, cm, and deployment) on a shrinkwrapped product typically costing 6 figures per install. We had between 6 and 12 writers (not outsourced temps, but actual writers). They were great. Many things went wrong at that organization, but one thing that wasn't broken was that we did have the doc team involved fairly early in the development effort, and it worked pretty well. Documentation was useful, as opposed to being just useless shelf-filler.
I'd advise you to keep the product used for your documentation pretty simple -- write it in MS Word, for example, and use RoboHelp or something like it to generate help files for the application (RoboHelp produces several types of help documentation, now, including the traditional windows help file as well as "compiled" html).
Try for a simple, clean style -- there's no point to super-fancy, convoluted page layouts or especially to making odd-sized manuals that don't fit with other books well. Word can do everything you need to if you keep the styles and layouts simple and clean. Quark and the other DTP packages out there are fine products, but in my experience, it's too temping with those tools to fall into the trap of providing stuff that's too much appearance and not enough substance. Plus, why bother with the extra expense of buying the DTP package?
Documentation is supposed to make it easy for users to get their various questions about your software answered, period. It doesn't have to be a fancy coffee-table book, nor does it have to be a marketing tool--the user's already got your software, after all. In the end, you'll do more to sell them on it if the documentation is **effective** rather than simply pretty.
Once you have the manual in MS Word, you can always generate pdf's if you want. To handle the change issue, you might want to produce a printed manual done in MS Word for release, then if you find you have to make post-release updates to the manual, you could make the edits to the original Word doc, and make the updated documentation available for download from a website in pdf format only, rather than doing another costly hardcopy print run. HTML documentation is often convenient, but generally doesn't print too well compared to a Word or pdf file if there's much formatting to it.
I'd also strongly recommend ensuring you version your documentation along with the software (i.e. same build label as the code, synchronize the documentation with your development iterations, etc.) -- it is, after all, a configuration item, and it really sucks to have documentation that doesn't match what the software does.
Finally, though I don't know what your software does, I suggest you consider that it might be better to break up the documentation into more than one manual. I'm sure you've seen this approach -- a user manual, and an administrator's manual, for example. Depends on how much material's involved and how well it breaks apart topically; it's not always a good idea. e.g. I'd say the old DEC VMS OS documentation took this way, way too far -- with a new install you'd get something like 3 to 4 feet of manuals, and you'd often have to goto several separate volumes to get the answer you wanted. Tons of detail there, but it wasn't efficiently accessible, IMO.
substanceOverAppearance
Tuesday, October 28, 2003
While the html version might be a good thing for search etc, I always like the option of having a PDF version.
Somethimes I want to print out the manual, and having to print out 34143 html paragraphs all on different pages is a bad thing.
Some developers offer a printer friendly html (entire doc on 1 html page....ala mysql) which is not bad, but makes printing different sections difficult.
Tapiwa
Tuesday, October 28, 2003
I think an important issue here (touched upon by substanceoverappearance) is running the documentation process concurrently with the development process and NOT waiting until the development is finished and then cramming the help doc writing at the end. This is what leads to 'crappy documentation'.
By taking this approach you can also improve the usability of the software with things like 'on screen tips' for fields, rather than hiding everything away in a help file.
Andre DuBuisson
Tuesday, October 28, 2003
I don't understand why people would prefer books to PDF. You can always print out the PDF and get something just as good as a book, right?
I'm also pretty sure the latest versions of reader support the mouse wheel, so I don't buy that complaint either.
Foolish Jordan
Tuesday, October 28, 2003
"You can always print out the PDF and get something just as good as a book, right?"
And then take it to a bindery, or what exactly?
Kyralessa
Tuesday, October 28, 2003
foolish jordan - you're right, current versions of acrobat reader do support the wheel mouse. However, whether you agree with it or not, it should be apparent from other posters to this thread that other folks do prefer hardcopy for certain circumstances. A vendor generally doesn't know how his customer base is split on this issue, unless they've done a survey on it. So it's probably a reasonable approach to strike a sensible balance such as somebody else suggested -- maybe do hardcopy for major version releases only, and electronic, easily printable versions for all releases, including minor ones and then perhaps too some abbreviated, highly-targeted electronic version for any significant patches or service packs. Hardcopy-lovers can have their paper versions, and print the electronic versions if they want to, and those preferring electronic docs can have it their way as well. Nobody's holding a gun to your head forcing you to use the hardcopy afterall, now are they?
kyralessa - my situation at work is such that I can do this all at work--say I have a 400 page pdf manual I want to print. I'll print it at 2 pages / physical page (standard windows printing option) on one of our laserjets, and if we had a duplexer, I'd do 2-sided printing as well (condensing the bulk of the doc by 75%), then use one of the coil-binding machines we have at work to bind the document. If you don't have those options at work and still want the hardcopy, most local copy shops like Kinko's in the USA, have such binding facilities and can do the whole printing and binding for you. Don't know how much it'd cost, but I'd guess it wouldn't be too bad. Probably worth it if the documentation isn't "crappy" as some have pointed out.
Actually, it occurs to me that there's another advantage unique to printed documentation; might be a little "rough" to implement, but could be viscerally satisfying, especially if the documentation is really, really bad and it's got you just disgusted over it, or if you just hate the software itself--you can always take the hardcopy manual to the can with you and use its pages instead of the TP! Kinda hard to vent your frustration at a vendor's bad documentation like that if all you have is a pdf. <grin>
anonQAguy
Tuesday, October 28, 2003
Actually, the best option would seem to be: supply a .pdf (html, whatever...) manual with the software.
Also, have a printed version available - for a price. Use Kinko's (or similar) to produce a small run as needed.
This way, the customers that don't want/need a printed manual don't have to pay for it and the customers that want a printed manual can either do it themselves or pay you for one.
Seems like a win-win.
RocketJeff
Tuesday, October 28, 2003
In all cases, documentation must come in electronic form at the minimum. If as a pdf, it should be INDEXED and cross referenced and the page numbers shown should match the page numbers Reader uses.
As a practical matter, if you software is very expensive, it MUST come with a set of printed manuals -- even if those manuals are merely photocopies stuck in a 3 ring binder.
If it's very cheap, a printed manual is not an option, but a quick reference card or quickstart brochure is a possibility.
In other cases, its up to you. Printed manuals can be sold as an add-on, either from you directly or from a print-on-demand shop for whom you have supplied with the most recent copy of the manuals.
If your software is tremendously popular, you don't have to do a thing -- after market tech writers will create the manual for you and sell it through all the usual outlets.
Of course it's hard to imagine software becoming that popular which doesn't have decent documentation.
One of the best solutions is to have html documentation and have an html viewer embedded in the software, which can bring up relevant sections of the documentation that relate to the form or dialog at hand.
Dennis Atkins
Tuesday, October 28, 2003
For Lingo ( http://www.lingolanguage.com ) the build script automatically creates a PDF file from the user manual master copy. The PDF file is included on CD. The user manual is about 50 pages which I print double sided using clickbooks. I decided to print the user manual only on demand.
Also there's a very large reference manual which is converted to hlp format. It is possible to print this but it's prohibitively expensive. I finally decided it should be a separately purchaseable item for people who really want a hefty printed manual.
IMHO the idea of printing out a large number of manuals which are then 'stock' belongs in the last millennium.
Bill Rayer
Tuesday, October 28, 2003
Yep the links are dead. Am I the 14,000th person to notice that?
Bill Rayer
Tuesday, October 28, 2003
I'm another person who hates using online (PDF, HTML, whatever) manuals. However, I also hate buying a hard-copy manual that takes up space on my bookshelf and is obsolete in a year or less.
The main reason I hate online manuals is having to toggle back and forth on the screen between the manual and the software I'm trying to learn about.
The best solution for me might be to have the manual in a Palm or Pocket PC format so I can put the manual on my desk like a book, and be able to refer to my computer at the same time. I don't own a Palm or Pocket PC, but this might be the one reason for me to get one. It would pay for itself in a year or so through the avoided cost of hard-copy manuals. I suppose I could just get a second monitor and do it that way, but I prefer having something small that I can carry around with me. I know I'm not the only person who reads software manuals in bed.
Brad
Wednesday, October 29, 2003
I use Help & Manual.
Lets you create both CHM (html) and PDF using the same source in a well explorer-like way.
You can export to another formats as well.
H&M creates Index, KeyWords, Search and so on automatically, and formats PDF according with rules you can define.
you can send both chm+pdf with your software and the end user can print the pdf easily.
have also a simple way to create capured images and so on.
Guillermo
Thursday, October 30, 2003
 Recent Topics
Fog Creek Home
|
