12/06 Editorial: IT'S TIME TO RE-INVENT THE OWNER'S MANUAL

(Every month, a new editorial is posted in Sound, Studio, and Stage. Your comments and feedback are encouraged!)

It

Interesting idea, almost like a Wiki Manual. The one thing I'll say in defense of the traditional owner's manual is that often, it's really great to have a hard copy. To have both a hard copy that perhaps serves as the baseline for the manual and a living, breathing updated manual would be wonderful.

Having written a couple of manuals myself, I agree that many of those we find for "our" gear are inadequate. Mostly, manufacturers just don't spend enough money on the manual, because they don't expect the users to read the manual, because they (the users) think that whatever they want to know they won't find it in the manual.

While there will certainly be some duplication in your manual collection, I think a manual should be able to stand alone. You shouldn't have to go to another book to find out how to connect the XLR outputs of the mic preamp to the RCA jacks on your sound card. You shouldn't have to go to another book (or more likely a forum) to find out why you need both ASIO and WDM drivers. You shouldn't have to go to another book to learn that you can't connect your CD player with optical S/PDIF to your interface with ADAT optical inputs (or if you can, that you can).

I like the idea of a quick start guide that shows you how to do something sort of useful quickly - if you don't get some sound out of it within minutes after getting it out of the box, you'll get bored or frustrated. But the quick start guide needs to include a certain amount of tutorial material, perhaps as an appendix.

A detailed technical reference should supplement the quick start guide. It's really hard to know how to organize this though because there are different possible entry points and you need to be able to quickly get to the right place. I like a printed manual that I can keep open while I'm looking at a screen or a front panel, but a PDF is also useful when you know that what you want to know is in there somewhere but you're not sure where.

I suppose it's too much to expect schematics, even for the parts that you might be able to fix like an analog mic preamp or a power supply.

Trouble is that all of that stuff is expensive, and it's simply not worth spending $50K or more to write a manual for a product with a manufacturer's life cycle of a couple of years.

As far as the maual keeping in line with software changes, that doesn't have to be an impossible task or one that can be put off until after the product is released. The problem is that not many developers (hardware or software) use a traditional development process any more. If you know the full product specification, you can write the manual. The wording on a screen might change, but by the time the specs are nailed down, the basic functionality is there and you can describe it. When a product is developed with the following process:

1. Marketing gets an idea for a product

2. Engineering starts working on it without having a clear idea of where they're going or when they've accomplished a goal, because they aren't working to a specification.

3. Marketing tells them it needs to be cheaper

4. Engineering gets a few new ideas every week and adds features to the product. Since they still don't know when to stop, they keep going.

5. Marketing tells them it needs to ship in three weeks. Oh, and it has to be cheaper.

6. Engineering sends whatever they have to the tech writer who has to figure out what the product is and what's important about it, and has three weeks to write the manual.

7. The product ships with things not working, and a page inserted in the manual tells you to go to the web site for the release notes and watch for updates.

you got trouble in River City. I've been there and written a manual in a week.

If everything cost 25% more than it does, there would be money to cover a decent manual and tech support. But Marketing says it costs too much.

I was gonna say a wiki, too.

>

You can also print out the edited manual, but I'm a big fan of the "Find" function.

No, YOU can print it out. I don't want to expend my time, paper and ink on something that the manufacturer should have given me. Go-Print-It-Yourself manuals really piss me off. But it's what the manufactureres do now, because of the cost, and besides, they figure that most customers aren't going to read it anyway.

I've sent PDFs to Kinko's for printing on occasion. A nominal 200 or so page manual with spiral binding costs between $25 and $30 for black-and-white printing. I figure it probably would cost the company about 1//4 of that, not insignificant, but they could (and should) afford it.

My Ampex MM-1100 manual is loose-leaf bound, and the service bulletins are right there in the same binder.

The FAA (where I used to work, and sometimes still do) has a very detailed published standard for what goes into a manual. It's a little outdated (some of the maintenance sections are really more appropriate for point-to-point wired tube equipment) but the publication details allow for change pages to accommodate modifications throughout the service life, which is frequently 25 years or more (not that it was planned to be that long, it just takes that long to replace something). When something gets changed, the group that maintains the manuals edits the page (or adds additional pages) and sends out a manual update package. It includes not only the actual change, but everything that changes as a result - an updated table of contents, parts list, schematic, etc. Whatever it needs to be complete and accurate. Occasonally changes will be pen-and-ink when it's just a typo or a spec change without need to change anything else.

When you're talking about a $200 effect processor, it's cheaper to make a new model than to keep up with the configuration management and documentation changes on the old model. I don' thave a $20,000 ProTools system. Maybe they do better with products like that.

That's right. If I'm buying a product, I should get an an owner's manual that I can flip through and read. a PDF doesn't cut it for me (especially when, like Pro Tools 5.1, the page numbers for the manual don't correspond to the PDF page numbers....{censored}ing brilliant).

The great thing about electronic manuals is that they have the possibility of being up to date.

The lousy thing about electronic manuals is that it is no fun to read online. This is especially true if it is a tutorial on a software product. Switching between windows is much less convenient than having a hard copy of the manual so you can leave your screen real estate for the software display.

Nevertheless, it seems to me that online manuals are the way of the future and there's nothing anyone can do to stop it. I agree with Mr. Rivers that it makes more sense for the manufacturer to print out since they can use bulk processes to do it less expensively. Still, in the real economic wolrd we live in, consumers vote with their money, and consumers generally would rather save the money than have a hard copy manual.

So, given that online is THE way of the future, I think an open source manual is an EXCELLENT idea.

How did they cross-up the page numbers? WTF?

It seems to me that most manuals are produced in some electronic format that could easily be converted to PDF. Why not sell the software with a genuine bound manual, and include a PDF on the program disk? How hard can it be when the manual was probably created in an electronic format - I don't think the software companies are using Underwood #5's for the tech writers.

That would be the best of both worlds. Like Craig, I like being able to use the "search" feature of a virtual manual. If a product comes with no hard manual, I'll usually only print pages as I need them for specific tasks.

Yeah, the subscription cost for a typical FAA-compliant Component Maintenance Manual runs about $700 a year. I wouldn't want to pay that... though it does stand as a standard of excellence.

I rather like the Widi model myself - - have a big web site where the non-penisoid manufacturers of pretyy much anything can donate their manuals to the public domain and allow users to append and insert text. It'd be nice to distinguish original content from added stuff, though. Maybe edits and insertions could show up as different text color or something.

>

I do like hard copy manuals, except...it's a big waste of paper and ink, given that indeed, many don't read the manual. Companies do have some economy of scale, but nothing like magazines and book publishing companies, and the cost of paper has climbed into the stratosphere the last few years. That's one reason why magazines are getting thinner; it's not just fewer pages, but thinner paper stock.

So environmentally, the PDF manual makes more sense. But overall, I must say that I prefer a GOOD (repeat, GOOD) online manual. When I got Sonar 6, I didn't even touch the manual, as I could just call up a subject and get the information I needed -- sometimes even with tutorials.

As online manuals are the way of the future, it behooves us to figure out how to make them so much better than hard copy manuals that no one ever misses the hard copy version.

The crucial element in what I'm proposing is a quality editor who can collate all the information into something useful. I bet it would even be more economical to pay someone's salary to edit the perfect online manual than it would be to print an inherently flawed hardcopy manual.

Yes, a quality editor would be absolutely essential in something like this, as it is a continuously evolving, living breathing document. And a company would obviously get major props if they did this for a long time, even after the product was discontinued, continuing to update it and to obviously keep it available to everyone.

I must say that I didn't like Reason's and Pro Tools' respective PDF manuals at first, but just five minutes ago I was back in Reason's manual because I had forgotten how to record mixer automation. Bang, I just clicked the highlighted text and it took me right to the information I needed. So I guess those of us who were English majors like myself and who like paper manuals will come around to the idea of online or searchable PDFs eventually.

Well, of course we're just caught in the gap before e-paper and technology like that finally works. I doubt we'll be having this problem ten years from now.

I gotta say, for large programs like SONAR and the like, I like having a hard-copy manual I can cart around and read when I'm AFC. Plus, I can keep in on my desk whilst I'm working and not have to do the CTRL-TAB shuffle when I'm trying to solve a problem.

Of course that depends on the manual too. SONAR's manual is an interesting case, because it's well written and comprehensive but it's indexing is somewhat lacking. In those cases the online help is much better for searching for terms (mostly).

I personally love the idea of a WIKI-esque resource than can take advantage of user-discovered shortcuts and the like. I think once search parsing gets a little more sophisticated it will become quite easy to find the exact solution or help needed for incredibly specific functions with this kind of help system.

So, I reckon we're kind of a limbo-like state. Perhaps we need to just invest our money in electronic paper stocks? :-)

I wanted to add that for things that require you to physically connect things (which may be getting less and less complicated now that so many things simply plug into a USB or firewire port) or for computers that are not online (like many people's DAWs), a PDF owner's manual can be a pain in the rear.

I have no doubt that we'll have more and more PDF owner's manuals or other kinds of e-manuals. But at the same token - and maybe I'm in the minority here - I don't find a computer screen, no matter what the size, the ideal place for reading. I book was developed over many centuries, and it's quite ideal for reading. You can take it with you, underline things, and get to a page quite quickly, all without getting eyestrain and carpal tunnel.

OTOH, a book doesn't have a Search Function and can get lost or misplaced.

Sooooo...these are probably some of the reasons why I feel that as a baseline owner's manual, a paper one is still best, and a Wiki-esque living, breathing owner's manual beautifully augments the paper owner's manual.

These are my comments as of today. I may change my mind tomorrow. You should my opinions with a grain of salt. After all, I'm using a G4 with Pro Tools 5.1 and have never owned an iPod or a cell phone.

Originally posted by UstadKhanAli After all, I'm using a G4 with Pro Tools 5.1 and have never owned an iPod or a cell phone.

Dude, that's awesome. I too have a G4 (running PT 7.1 though--highly recommended). As for the iPod or cell, they're lifesavers.

Unfortunately, most of them don't get updated. Also, with different versions of the manual and the product/software floating around, it's easy to have the wrong manual for whatever you're trying to learn about. We who post every day think it's easy to update material on a web page as required, but in practice it rarely gets done. It's one thing if a user on a forum answers a question or explains a not-yet-documented feature to another user, but when the company does it, there's an implication of responsibility that requires thorough scrubbing of every word "officially" published. That's why it either takes too long or never gets done.

It's also difficult to read on the couch or on the can. I'll often keep the manual for a new piece of gear within reach and just browse through it to see what's there that I might not notice otherwise.

This is unfortunate - those of us who are willing to spend a reasonable amount more for a good manual (and more important, a product that's delivered in finished form so it won't require constant updates that affect the manual) are not offered that opportunity. You want a printed manual with that? That'll be $100.

Mackie took a rather creative approach to the publication of an analog mixer reference guid that I wrote for them. It was originally concenived as a "bible" that would be packed in printed form with every mixer they sold, and a quick start guide referencing the individual product would get you started and point you to the appropriate sections of the larger manual for more details. But by the time they got around to deciding to publish it (the idea of packing it with every mixer was shelved long ago) they were selling mixers (under the Tapco brand) that probably cost less than the publication cost of the mixer book.

So what they did was split it up into a zillion PDFs, one per chapter, available free for the downloading. You could print it yourself, or just read it on your computer. In addition, they set it up with one of those print-on-demand publishers so that for $29.95 you could order a printed copy. That seems to be reasonably fair.

But updates? I updated it (before it was published) to cover the original Only line, but now the 4-bus series has been updated and they haven't added a new section to cover it. And I suspect that they probably won't.

Mackie Compact Mixer Reference Guide

You have to be very careful about that. If someone updates it with the wrong information, a lot of people could be misled. What would be a good idea might be to have a designated person who, say, once a month, would take all the suggestions for updates that came in, review and edit them, and then publish an on-line update. But it's all about money, and they don't really want to spend any. In terms of salary (or a contractor) it would probably amount to about $2,000/month. That can really eat into the cost of a low-priced product.

This is something that you can fix in Acrobat if you're smart enough. It has to do with setting the size of the paper properly.

This would be a good idea for hardware, and with software copy protection becoming pretty much universal (again), it can work for software as well. But sometimes, the manual is the only form of "copy protection" that a software program has. If it was easy to get a copy of a manual ("I have a copy of Sonar but no manual. Can someone please send me one?"). A PDF manual just makes things easier for dishonest people. I've occasionally been asked for a PDF copy of my Mackie hard disk recorder book, and I've send one on an individual basis, but I figure that if I offered it for sale as a PDF, there would be a lot more copies out there that I didn't sell.

Yeah, but isn't that a pain? I have Sound Forge which has a quick start manual plus a detailed manual a a PDF. Both of them suck, but the PDF is much larger.

I think we need to clarify the meaning of "online" in this context. When I think of "on line" I think of going to a web or FTP site, downloading something, and then dealing with it on my computer. I think what you're talking about here is an "in line" manual. In this model, the "help" is aware of where you are in the program, and asking for help will give you a context-sensitive start. I have no idea of how they do this, but I agree that context-sensitive help is quite often helpful. But where it doesn't help is if you're off track. It doesn't know what you're really trying to do. How often has someone asked a question in a forum, and after some probing, you find out that they really have a more fundamental problem? Context-sensitive help isn't that smart yet.

I cost too much. How about you?

But . . . .the reason why a product gets discontinued is so that they can stop supporting it. I see people who are first time users of Mackie hard disk reorders and digital consoles, hardware that's been discontinued for a few years and is probably now in the hands of its third or fourth owner. And they want to see the product updated to offer features of current competetive products.

It would be wonderful if companies in this field had what's known as "sustaining engineering" - to keep what's was a great product when it was introduced in line with currently introduced similar products. This can work with a $500,000 console (I've been told that 20% of the cost of an SSL goes into the pot for long term support), but for a $300 program, they want you to buy the new $300 program.

But why should users have to discover those shortcuts? Why doesn't the manufacturer tell you about them in the manual? The sad story, and I alluded to this in my first post on this subject, is that shortcuts should be part of the product's specification. The people specifying the product should decide on what things need shortcuts and, while initially they might not specify that Ctrl-S would save something (though it's a good idea to specifiy things that should have become universal standards for common functions) at least they should know that there's a shortcut to save. The manual writer, looking at the specification, would know to include "Save" in a table of shortcuts and if the programmers didn't tell him the secret code, he could seek it out.

The users shouldn't have to discover what the programmers put in and didn't tell anyone about. But both happen.

A game I sometimes play which has semi-regular updates had a 3rd party introduce a companion manual which was sold in a 3-ring binder - updates to the game would then be released as .pdf pages, which an end-user could simply print out and put in their binder.

This could work if the manual was released as a package of pre-punched printed sheets for insertion into a binder. (Maybe the customer buys their own binder, maybe they have one provided...) A .pdf is also provided with the software, and updates are released as pdf printable pages - which are easily inserted into the existing .pdf (actually, not sure if reader has this function - acrobat does)

Maybe Adobe could have an "addenda" feature - checks for updates at the reference site saved with the manual, and inserts pages or other corrections automatically.

Something that I proposed to Mackie (which they thought was a darn good idea but never implemented) was to provide the manual as a package of 3-hole punched pages. When the customer sent in the warranty card, he'd get a binder with a printed front and spine so it would be easy to identify, and a set of index tabs to separate the sections.