Slashdot Mirror
Are Printed Manuals Dead?
Bantik asks: "I work for a software publisher, and there's a raging debate going on upstairs about whether or not we should continue providing printed manuals. I think that between a program's Help menu, documentation in PDF form on the program CD, and the online documentation on our Web site (HTML and PDF), we're fine. What do /.'ers think? Are printed manuals a thing of the past? And what major software vendors are going down the Paperless Path?" While some of my peers would just love to declare paper dead and a thing of the past, I feel that physical manuals are still very necessary. There's nothing like having a reference you can flip to and computers aren't common enough that there's one at every place you might find the time (or desire) to read. Thoughts?
See /usr/src/linux/Documentation/sysrq.txt of your Linux install.
~ ~~~~~~~~~~~~~~~~~~~~~~
~ ~~~~~~~~~~
* What is the magic SysRQ key?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is a 'magical' key combo you can hit which kernel will respond to
regardless of whatever else it is doing, unless it is completely locked up.
* How do I enable the magic SysRQ key?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You need to say "yes" to 'Magic SysRq key (CONFIG_MAGIC_SYSRQ)' when
configuring the kernel. This option is only available in 2.1.x or later
kernels.
* How do I use the magic SysRQ key?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On x86 - You press the key combo 'ALT-SysRQ-'. Note - Some
(older?) may not have a key labeled 'SysRQ'. The 'SysRQ' key is
also known as the 'Print Screen' key.
On SPARC - You press 'ALT-STOP-', I believe.
On PowerPC - You press 'ALT-Print Screen-'.
On other - If you know of the key combos for other architectures, please
let me know so I can add them to this section.
* What are the 'command' keys?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
'r' - Turns off keyboard raw mode and sets it to XLATE.
'k' - Kills all programs on the current virtual console.
'b' - Will immediately reboot the system without syncing or unmounting
your disks.
'o' - Will shut your system off via APM (if configured and supported).
's' - Will attempt to sync all mounted filesystems.
'u' - Will attempt to remount all mounted filesystems read-only.
'p' - Will dump the current registers and flags to your console.
't' - Will dump a list of current tasks and their information to your
console.
'm' - Will dump current memory info to your console.
'0'-'9' - Sets the console log level, controlling which kernel messages
will be printed to your console. ('0', for example would make
it so that only emergency messages like PANICs or OOPSes would
make it to your console.)
'e' - Send a SIGTERM to all processes, except for init.
'i' - Send a SIGKILL to all processes, except for init.
'l' - Send a SIGKILL to all processes, INCLUDING init. (Your system
will be non-functional after this.)
* Okay, so what can I use them for?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Well, un'R'aw is very handy when your X server or a svgalib program crashes.
sa'K' (system attention key) is useful when you want to exit a program
that will not let you switch consoles. (For example, X or a svgalib program.)
re'B'oot is good when you're unable to shut down. But you should also 'S'ync
and 'U'mount first.
'S'ync is great when your system is locked up, it allows you to sync your
disks and will certainly lessen the chance of data loss and fscking. Note
that the sync hasn't taken place until you see the "OK" and "Done" appear
on the screen. (If the kernel is really in strife, you may not ever get the
OK or Done message...)
'U'mount is basically useful in the same ways as 'S'ync. I generally 'S'ync,
'U'mount, then re'B'oot when my system locks. It's saved me many a fsck.
Again, the unmount (remount read-only) hasn't taken place until you see the
"OK" and "Done" message appear on the screen.
The loglevel'0'-'9' is useful when your console is being flooded with
kernel messages you do not want to see. Setting '0' will prevent all but
the most urgent kernel messages from reaching your console. (They will
still be logged if syslogd/klogd are alive, though.)
t'E'rm and k'I'll are useful if you have some sort of runaway process you
are unable to kill any other way, especially if it's spawning other
processes.
* Sometimes SysRQ seems to get 'stuck' after using it, what can I do?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
That happens to me, also. I've found that tapping shift, alt, and control
on both sides of the keyboard, and hitting an invalid sysrq sequence again
will fix the problem. (ie, something like alt-sysrq-z). Switching to another
virtual console (ALT+Fn) and then back again should also help.
* I hit SysRQ, but nothing seems to happen, what's wrong?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are some keyboards which do not support 'SysRQ', you can try running
'showkey -s' and pressing SysRQ or alt-SysRQ to see if it generates any
0x54 codes. If it doesn't, you may define the magic sysrq sequence to a
different key. Find the keycode with showkey, and change the define of
'#define SYSRQ_KEY 0x54' in [/usr/src/linux/]include/asm/keyboard.h to
the keycode of the key you wish to use, then recompile. Oh, and by the way,
you exit 'showkey' by not typing anything for ten seconds.
Help should be placed in logical places. Technical, man-page style documentation should probably be online since you just need quick reference. However, it is sometimes nice to have overviews on paper so that you can remember syntax, yet not have a 3" thick bundle of paper.
The flip-side of the coin to is make sure the user has enough documentation to get started. It can be hard to find the appropriate pdf or help system if you are new to a program. Another instance of this are all the READMEs that tell you how to ungzip the distribution. Of course, the README is already _inside_ the gzip, so....
"Hello, tech support"
"Hi, I forgot my password. My username is bjk4"
"Ok, I just emailed you your password. It should get to you in a minute."
"Thanks."
-B
A hyperlinked manual is certainly useful. But I will continue to want paper. I even print long man pages when I need them. The better print quality of a manual is easier on the eyes, and just plain more comfortable to hold. It's also easier to browse; you just can't "flip thorugh" a computer screen.
Digital displays won't make serious inroads into printed products until DPI reaches *at least* 300, and there will be a serious demand for paper just on visual quality alone until at least 600dpi. ANd even then, there will be a market for paper.
hawk, who will give up printed manuals when you pry them from his cold dead fingers
Speaking about the HTML access.. what about people who dont in fact have web access? That limits one of the sources.
--
Scott Miga
suprax@linux.com
What level of expertise are your manuals? For example, I never looked at manual for Windows or Microsoft Word back in my Windows days because they are such intuitive, easy-to-use programs. However, at the same time, I could easily see a disaster occuring if Cisco decided to do this. Some of their reference libraries are several volumes and total 2-3 feet of printed material each. Killing them would not be a good idea. Remember two things - this printed manuals are far, far easier to search quickly through (even with no word/regex search, it's just a lot easier to browse through one and find things than with a manpage), and two, it is uncomfortable to read on a computer for extended periods of time.
So, if your company makes mice, by all means, distribute a readme.txt file and be done with it. However, if they make Inverted Confustication Delivery Systems with added Defrillication Modules, then please continue to distribute hardcopy documentation.
--
I think there is a world market for maybe five personal web logs.
'nuff said. :)
Tell those cheap marketing folks "upstairs" that at the very least installation and quickstart guides must be provided in print, and that they must at least sell printed versions of all documnetation, especially that boring, repetitive and bulky "reference" stuff.
PDF documentation is nice to have, especially if it's searchable, indexed, and linked. It's good to be able to print a book yourself if the prnted copy has walked away. But a stack of 8.5"x11" or A4 printouts in a binder or held together with a big paperclip is a horrible substitute for a bound book. And reading docs onscreen is nice unless you're trrying to get work done and read the docs at the same time. Clicking back and forth gets tedious quickly.
HTML docs and context-sensitive help are nice for some things. But again, they are used differently from a nice book. Sometimes you just need a book. This will change when large-format high-resolution (>200 dpi) e-book readers become available, but until then the rule should be: if you have enough documentation to make a 200-page book, you must offer it as a 200-page book.
Marketing folks will argue that since you've made the sale, it doesn't matter what format the docs are in, because you've already won the customer. But that's not true. Software with awkward, inaccessible documentation makes for unhappy, frustrated users, and when the product comes up for re-evaluation 18 months later, that frustration gets expressed in a desire to work with something "less awkward".
You can have the best product on the market, but if your documentation is frustrating to work with, then your product is frustrating to work with.
Ask your company's inside-sales people, who deal with current customers. Customers tell them what they think of CD-only documnentation. And it's not nice.
Printed manuals are essential. They allow me to review documentation when I don't have access to the computer or program. I could be on a plane, the computer could be dead or I might just not like reading things online.
I'm sure everyone will agree that a real book is far easier to read than a monitor. The insignificant cost of providing a manual to you customers makes up for far more than it's cost in time and effort
You don't exist. Go away. --SysVinit Halt
I work in a company where we are using our own product to create documentation. I (and the rest of the documentation team) would love to put together a printed manual, since our product can;t yet produce high-quality printed output. The engineering managers, to a person, have given this idea the thimbs down. "Our users won't need a printed manual!"
One of these managers later demanded a printed copy of our documentation to hand to a new employee... Why? "Oh, well, it's hard to read on screen." They wouldn't give us the resources to do a print-freindly version, nor the engineering resources to make the product produce better printed output, and on top of all that, they expect us to waste time printing out the document so it's handy for new engineers.
And people wonder why documentation is so crummy...
They Just Don't Get It.
HTML is only easily searchable if your doc is stored in one big HTML document! AFAIK none of the popular browsers can search multiple HTML documents in any reasonable fashion.
PDF, for all its faults, is at least searchable, and handles large documents much better than HTML does.
Please give me docs that I can sit down with outside and leaf through at my leisure, with no need to be anywhere near a computer.
And please give me online docs in html format (at minimum!) - no PDF or postscript please, unless this is also accomanied by html.
By far the most important version is the online, hypertext, searchable version. Whenever there's a tradeoff to be made for cost reasons, favor the online docs.
On the other hand, when I pay big money for a software product I *expect* printed docs and if I don't get them I probably won't be back a second time.
--
Life's a bitch but somebody's gotta do it.
The reality is that they want to save money. It costs serious money to write, edit, design and print high quality manuals.
I recently bought a retail copy of Microsoft Office 2000 and it had no manuals. This is not a cheap software package. I felt I had been ripped off (again) by Microsoft.
Help files and PDF files are not a substitute for printed documentation. You can't do high quality graphics and book design when the output device is a CRT. A two-dimensional display is not an adequate substitute for a book.
Mea navis aericumbens anguillis abundat
I refer to my Linux books and my printer manual and other books all the time, to remember things like what cartridges my printer takes and how to do certain things. A printed book still works even when you've fried your X server or removed /etc. Although online resources are convenient and useful, books still have a place.
Switch the . and the @ to email me.
Good examples of what I find useful are the O'Reilly "In A Nutshell" books, the O'Reilly main series, the "For Dummies", and the Waite Group's "How-To" books. Those generally present a lot of information, but in a logical, useful way. They do leave out less important detail. The on-line documentation should then document every last bit.
I'm still personally a huge fan of printed documentation. Help systems still clutter up the interface in a huge way... Hit help, 1/3 of the screen gets covered by the help window. Some programs make the help separate programs that can end up behind the program that you need help in, so you need to constantly flip back and forth between the help window and the application window if you can't remember all the steps required to do whatever it is you're doing. Compare that to reading the index of a book, spending 15 seconds flipping to the correct page, laying the book next to the keyboard so you can type and read at the same time...
:).
That, plus sometimes, if i'm really interested, i'll read the manual at places besides the computer... like on the train, on the couch, etc... Hauling around a laptop is way too cludgy if all you want to do is read a book. You can't really dog ear pages in online references, nor can you apply yellow highlighter to your screen (unless you are able to scroll the window so what you wanted highlighted lines up perfectly with where it was when you actually drew across the screen with the marker at some previous point... but even then, you'll end up with yellow streaks across the screen
Lastly, with PDF documentation, 95% of the work is already done, in the writing and typesetting of the manual. All that needs to be done is the actual printing. Even for a large manual, that's still really only $2 or $3 extra for the documentation in printed form. That makes it cheaper for them to distibute the manual than it is for you to print a whole 200 page manual to an inkjet or laser printer.
As a last point, notice that software prices stay the same despite the lack of manuals these days... No matter what the justifications that programmers, QA, or engineers point out, it's all probably spurred by CFO's somewhere going "how can we earn just a few more dollars per box shipped? That manual can go!"
So download another PDF viewer, it is an open standard.
I'm a loner Dottie, a Rebel.
If you've ever had a computer/OS/ect not work, you know the advantage of having a printed manual. If you're stuck in a new OS on a new system that you have no clue as how to get it running do you want the box to say "We saved paper by only providing an on-line manual." I really doubt you do. Besides not needing any electronics to use, printed manuals are user friendly. Anyone with properly working eyes and literacy can use a book, the same can't be said for on-line manuals.
I'm a loner Dottie, a Rebel.
When I decided to learn Perl, I stumbled across Perl 5 By Example, http://www.codebits.com/p5be/. The online version pays for itself by advertising. I contemplated purchasing a hardcopy of the book, or possibly of a different Perl book. Then I considered my situation.
I am always on the go, I program from a half dozen different terminals in the course of a month. Any reference books I have access to, generally sit on a shelf at home, or a shelf at work, and I don't tend to carry a library on my back. But every computer I access has access to the internet, so the only way to have a book be conveniently accessible is to have it online.
Some people talk about cost of printing, and environmental issues, and cheaper distribution in digital form, but while these are important, they are not my primary concern. Internet based references have recently become more accessible than physical references, especially for highly mobile people such as myself.
For games, I don't think there's any question. You need the printed manual. In many cases your machine is locked down with the running game paused when you need to refer to the manual. Reading a PDF or other online document would mean quitting out of the game. And who wants to do that? If you took the time to refer to the manual at that point in the game, you're obviously too into it to quit out then.
And even if you can ALT-TAB out, do you really want to try that in 'doze and risk crashing your game, or at least slowing it down when you alt-tab back? I couldn't begin to count the number of times I paused Baldur's Gate to refer to the manual for some statistical or other data, for example. Having to alt-tab to a web browser would have made playing the game suck, and caused me to have to reboot at least twice as often as I otherwise would have had to.
Even Microsoft has greatly reduced the manuals that they provide nowadays. Programs that used to be distributed in huge boxes are no longer distributed that way. Especially OEM software, which in many cases relies almost exclusively on online documentation.
I am responsible for software production and distribution at General Motors, and we are moving our release notes from paper to paperless. That is the general direction for GM anyway.
I don't think paper manuals are really a necessity. I personally don't use them, instead I always look on the CD for documentation in *preferrably* HTML format, but PDF is ok, too.
I like HTML because it fast, easily searchable, and viewable by standard Web browsing software, which virtually every computer already has installed nowadays.
My journal has hot
YOU CAN SCRIBBLE ON IT.
You can highlight, you can underline, you can make notes in the margins, you can note where the tech pubs dudes fscked up... you can put those little flourescent sticky tabs on the critical sections and scribble what they are on the tabs, thus producing over time a crude but bloody effective search engine...
As long as you can still print the HTML/PDF/Word doc/whatever, geeks will continue to do so, for this very reason... and, of course, the fact that it's portable and not power-dependent, and just plain easier to read. But the scribble factor is quite large... and often overlooked.
--
Nuts on modding up the AC's. Make them login.
The reason is simple: most software packages are far too complex to document completely on paper so why bother?
Basically there are two ways you can use a manual:
- as a tutorial.
- as a reference.
A tutorial should cover all major ways of using a package. Typically you don't proceed through a tutorial linearly but you pick topics that interest you in the order that is convenient for you.
A reference should be complete and easy accessible. Those requirements cannot be fullfilled by a paper manual (at least not without increasing the price of the software package significantly: thick manuals are expensive).
Both ways of using a manual can be done using online manuals. For tutorials I prefer online because it is easier to use (examples you can play with, animations, search). Also it is possible to provide references to other relevant portions of the tutorial. Take the java tutorial as an example. It is far too large to print in one book (the swing tutorial alone is hundreds of pages) yet it is very desirable to keep it complete (not to mention up to date). I don't think many people can claim to have read it completely. Given the choice I would alway prefer the online version since the best feature of the tutorial is being able to find documentation on all related issues real quick.
The same goes for references. Lets take the java API as an example. I wouldn't care for a 1000 page dump on paper of the Java API documentation. I know there are many expensive books that provide exactly that (I don't own any) so apparently there are people who think differently about this. However I wouldn't want a software company charge me for a thick (expensive) manual I won't use anyway.
An online version is so much better (links to related classes, links to relevant portions of the tutorial and vice versa, search facility).
Most software packages these days only ship with some very basic paper documentation (installation, how to get started, how to browse the online documentation). Having the installation instructions on paper can be handy but a readme file is ok for me too. Since I know how to insert a cdrom and find the readme, the dead trees are wasted on me. But I suppose it looks nice to ship some paper along with the cd.
I no longer judge a software package on the paper documentation but on the quality and accessibility of the online documentation. PDFs and postscript files are bad in my opinion (limited or no interactivity). Winhelp or HTML is much better. I mention Winhelp because that has search built into it while with HTML the searchpages have to be generated statically (limiting their usefullness).
But even the use of offline documentation is limited. In the case of Java I usually refer to the documentation at javasoft since that is the most up to date version.
Jilles
then I'd suggest a nice printed manual with a CD on the inside cover. You can have the best of both worlds.
Do a printed manual. They are invaluable. As has been mentioned they are easier to read, more portable, and work even when your computer isn't. They are what I want to work with when I am just learning a program. On the other hand,
Do a soft-copy manual and put it on a CD attached to the inside cover of the printed manual (ala those stupid books with "examples" CDs). I often find that AFTER I am familiar with a product, usually from reading the hardcopy docs, that when I want a quick answer I prefer soft-copy, searchable docs.
Skippy
"False modesty is the refuge of the incompetent." - The Stainless Steel Rat
As much as I use computers and like to be at the bleeding edge of every development, I still want good old fashioned PRINTED manuals.
We've got some software that comes with software-only manuals in the company. Inevitably what happens is that people just print it out anyways. It would make the customer a LOT happier to heft a real manual in the box.
I see 2 main issues to software docs:
- No screen is as good as a printed piece of paper to read. Yet. And I've got some darn fine LCD's at my disposal. (including a 13.7" baby that will handle 1280x1024)
- It is WAY more convenient to flip through pages by hand than using any search function.
I feel this discussion is rather like
the digital/analog watch discussion.
Sometimes we geeks are rather quick at
dismissing older technology.
We've all heard it:
- newspapers are dead
- printed books are dead
- analog watches are dead
Etc..
The truth I feel, is always somewhere in the middle.
Searchable computer-manuals are great.
But having to open up a browser to read instructions or references is not the same
as just having it on paper.
Not everyone has dual-head display, and I'd like
to let my work have total focus on the desktop.
Virtual desktops are OK, but I really like a
printed manual.
Besides, some things will always need separate
manuals.
How much good does a PDF-manual do you, when
need help trying to get your OS to run properly?
That's great, I need the the PDF-manuals to
get the OS working properly, but if I could read
the PDF-manuals, I wouldn't need them.
Talk about the chicken and the egg...
Printed manuals is much, much better for newbies.
Some application could probably make it with
just browsable manuals on disk, but not all of them.
For now, a good printed manual is actually a reason why someone buys an application instead of
just pirating it, or downloading it legally (when we're talking about OSS).
This is semi-OT, but, is it just my impression or has the amounted of paper printed indeed increased exponentially with, in the last decade or so, computers having made printed material supposedly “obsolete”?
(Yeah, that sentence was rather a mouthful. Let me try to say that more clearly.) I get the feeling that, in the computer age, the use of paper has increased tremendously. I'm not just talking about twirps who feel the need to print thousand-pages long listings with just one column of digits on each page. I mean that not only have screens not replaced paper but computers seem to have made the need for the latter even higher. Probably because, before computers, the producer of some data used to print the data on paper; now it's the users who print the data (“data” in the broad sense—this includes manuals), even when they might not use it. (All right, this analysis is really simplistic; please fill in the missing details.)
The Xerox, ahem, photocopy machine, was the first step in the massive-paper-consumption trend. The computer was the second. Clay tablets, anyone?
Having said all that... O'Reilly includes their own java-based search engine with their CD Bookshelf series. And their offerings are a series of individual HTML files.
So yea... you don't need to have one fat file to search if you're willing to put a bit of extra effort in to it (or provide the tools as part of the documentation).
It exists, though it doesn't do PDF, and it's still a little expensive:
n quiry.asp?userid=4J8E9GM4QN&srefer=&isbn=0 641046197
http://shop.barnesandnoble.com/booksearch/isbni
Or, you could get a Palm or WinCE device. My understanding is that the WinCE's larger color screen would be ideal for this sort of thing. (And I think you can get a PDF reader for WinCE.)
Disclamer: I have never used thier service, only heard about it.
However, FatBrain (www.fatbrain.com) offers what they call "Print On Demand" services which permit authors of software (amongst others) to provide electronic manuals, and give them an option to buy the printed manual from FatBrain. What makes this system interesting is that there is no risk to you: they literally print the book on demand just before shipping. That way, there isn't excess inventory, and you could even set the print costs to just above the cost to print the manual--that way, your company saves on printing costs and inventory costs, and for those (like myself) who want printed manuals, they have a low-cost alternative to printing the whole thing out.
My understanding is that print-on-demand services is also provided by Barnes and Nobel, though I couldn't find any information on their web site.
For more information about FatBrain's print on demand services, visit http://www1.fatbrain.com/inf oexchange/program.asp?vm=c
Comment removed based on user account deletion
Indeed. I also don't consider .pdf files to be any more useful than other forms of documentation. The only reason to use something like pdf is that they want to give you something that looks like a book without actually giving you a book. Kind of like taking the bus is just like driving a car without actually driving a car. There are probably other formats that would be more useful electronically if you can just break out of the "it must look like a book" mindset.
Wandering slightly off topic, but this reminds me of the mournful transition in the Windows world from simple, human-readable/editable INI files to that hideous monstrosity that is the System Registry. With INI files, I could at least look at them and maybe figure out what went wrong with the software in question, even if that software was Windows.
In really desperate situations, I could resort to COPY CON WHATEVER.INI, which I did once out of necessity. Try editing the Registry like that when you can't get the GUI to boot. Heck, try to edit the Registry even with the GUI tools -- now there's a black art on par with, say, configuring the X Window System by hand.
Well, maybe configuring X is easier. :)
--
"I have a good idea why it's hard to verify programs. They're usually wrong." --Manuel Blum, FOCS 94
This is a non-debate. I don't have an extra CRT to lug around with me to read manuals and I'm not going to waste my time with stupid window and web page metaphors when I can just flip through a damn book. Reading documentation on a CRT is awful. The necessity of paper documentation should be proportional to the complexity of the program. No, don't print out the man page for ls, but I'll be damned if I can't find a book on the OS I use.
I would also like to personally throttle cheapskate game developers who only include documentation in an electronic form - I'm not going to friggin flip back and forth between a damn PDF file in the middle of a game.
It's 10 PM. Do you know if you're un-American?
I can read for hours and not get a sore wrist. I can curl up in a chair, or on a couch, or -- DEAR GOD NO, NOT THE SHINY BRIGHT YELLOW THING -- even go outside and catch some sun.
But even if I'm just clicking my way through a PDF or HTML file, indoors, in a chair, it's the exact same clicky-clicky motions I make all day. It still causes stress on the wrists.
Give me a hand-held PDF reader with a decent battery life that won't cost me my left testicle, and I'll throw out the paper and sit outside with that instead. But until then...
You cannot apply a technological solution to a sociological problem. (Edwards' Law)
There's a lot of stuff you still can do better with a paper document than with an online book:
* Use it when the machine is down.
* Use it when something is fouled up, hung, or just busy with the thing the manual describes. (In particular, your first times through a complicated process you don't want to make it still more complicated by flipping to help screens - which may not be fully available at every micro-step of interaction.)
* Stick a finger or a bookmark in one passage while reading another, and flip between them (or among several).
* Highlight important passages.
* Take notes in the margins.
* Study it in bed.
I could go on.
Further: display technology is still orders of magnitude away from being able to display as much, as conveniently, as a couple hundred pages of paper. Imagine trying to read in bed with a megapixel monitor sitting on your belly. Then think about staking up a couple hundred of them, to simultaneously display the whole writeup.
Which is not to say that online help isn't good, too. For starters, it can do things that are difficult on printed paper, such as generalized searches. (An index is a pain to generate. And even when present it only covers what the writer thought was significant, which is usually not everything the reader wants to look up.)
Bantam Dominique roosters crow a four-note song. Once you've heard it as "Happy BIRTHday" you can't NOT hear it that way
Help screens have natural boundaries that tend to bias the author toward "soundbite" terseness. Printed manuals aren't as restricting, which makes them more suited to more leisurely examination of deep subjects.
Cloning a paper-style manual to a screen doen't really help: The screen's limitations make reading a long flow more difficult. (Try reading the same document in Adobe Pageview and on bound paper.)
Bantam Dominique roosters crow a four-note song. Once you've heard it as "Happy BIRTHday" you can't NOT hear it that way
Please convince them that they are right. :) They shouldn't provide printed manuals. That way, when I go out and buy printed guides, I'll have a leg up over my competition.
But, seriously, anyone who has ever had a complete set of encyclopedia knows deep down that books are incredibly useful. Now, if your help system was fully indexed and quickly searchable, then I would prefer the help system, but it's got to be on my local machine. I'm not willing to set up a net connection on every bloody computer I work on just to get at some slightly obscure command-line switch.
Dave
Barclay family motto:
Aut agere aut mori.
(Either action or death.)
Some good points have been made here about the relative merits of print vs. electronic manuals. Judging from the fact that a quick search didn't turn up any references to translation, I don't think that issue has been dealt with. One of the things that online documentation makes possible is the distribution of a single software package with documentation in a number of languages. This can be extremely important for open source projects where there is no way to recover the cost of translation and printing in many minority languages. Sure, there are large, easily definable markets for Linux with English, German, French, or Spanish documentation, as well as others. What about less widely used languages?
In thanks for some open source translations I did, MandrakeSoft sent me a copy of Mandrake 7.0 (thanks, especially to Pablo). Somehow I got on the list for a copy with Spanish documentation. My conversational Spanish is rusty and my technical Spanish is non-existant. And it doesn't matter. The full English documentation is on the CD ROM. Besides, I translated the quick install instructions, so I ought to be able to find them again.
The point I am driving at is that no Linux distribution is going to make money selling a distribution with printed documentation in Esperanto. The potential market is rather small, and is spread throughout the world. Yet because of the nature of Esperanto as an interlanguage, Esperantists have a need for an internationalized computing platform that can handle their own native language and Esperanto. Given the open source model, and volunteers, it is possible to have support for many languages, each for the tiny cost of the space it's documentation occupies on a CD ROM. If there is a market for the printed documentation, the printing and distribution of that can be handled separately.
The net will not be what we demand, but what we make it. Build it well.
If you think it's the type of program that people might go out and buy a book for, include a manual.
It doesn't have to be a 600-page "everything the developers ever envisioned for this piece of software, and how to use it, in excruciating detail", but it should at least allow someone to learn the program without refering to online help, and enough to tell them how to use the most common features.
If people didn't want printed manuals, how would SCC stay in business? (Are they still in business? maybe bad example.) People buy printouts of stuff they can get online for free. Clearly, they like paper.
--Kevin
Basically, there are three advantages for paper documentation:
Advantages of online documentation include:
Giant reference manuals, which are seldomly used, are a good example of documentation that can be placed online only.
One thing you should always do is provide all of your documentation electronically. A user should be able to view all the documentation online if he chooses. Never provide any documentation in paper format only. You may also want to sell two versions of the application: one with and the other without paper manuals. The version without paper manuals should be cheaper.
And the men who hold high places must be the ones who start
To mold a new reality... closer to the heart
Customers liked them so much that we started releasing updates to them. We went from releasing them every 2 yeas to every year, then every 6 months, then every 3 months.
When the work sterted to get overwhelming (and our customer base grew) I went in to ask for another engineer to help the project keep on schedule. In the meeting, my boss informed me that we spent over $75,000 in the previous year just on printing and distribution and asked that I look for new ways to lower that cost. Then, and only then, would he consider bringing on additions to the staff.
The lesson here is that a printed solution doesn't scale well. It's fine for a small user base, but as that base grows, a printed solution adds up to real money.
In the end, we went back to giving one manual with the purchase of the product and gave away newer versions of the docs on-line to keep customers satisfied. We increased our update schedule to every month, and hired the extra engineer.
___
Oddly enough, I generally find the man pages that come with the assorted free software that I much prefer to be comprehensive and useful. Go figure.
I'm trying to teach myself to set people on fire with my mind... Is it hot in here?
Manual comes from Middle English manuel, from Middle French, from Latin manualis, from manus hand. So etymologically, manual (in the adjective form) refers to something relating to, or involving the hands. Now, when we move to manual as a noun, it has taken on the meaning of a book. It is a special kind of book though, "a book that is conveniently handled; especially : HANDBOOK." Further, a handbook is "a book capable of being conveniently carried as a ready reference." (Handbook goes back to manual; they are synonymous.) From what we have learned now, a manual is something that you take with you and can easily be used in your hands. That is why they have so much over anything on a computer. Many have already said that the computers are not portable, they hurt your eyes etc so I won't go into that.
I dislike even the ebook devices (whatever they are called.) A book is a book and nothing else will ever be a book. It is something that can't be compared, you can scribble on it (as said in other posts), you can put your own markers in it to "search to," and the feeling of holding and reading a book is something special unlike anything else.
Excuse me if I babbled too much.
When I'm trying to get up to speed on a particular system, I'll often read/skim the manuals from front to back. You simply can't do that with on-line docs, for two reasons:
1) Reading off a monitor sucks for long periods of time.
2) The organization of on-line docs sucks. You get the added benefit of hyperlinking, but you get the negative aspect that usually people don't put the time into organizing the docs into a linear way that can be read cover to cover.
Other than that, it's also way easier to use a manual that I can keep open to relevent pages while I'm programming on the system. I guess a two-monitor set-up might work, but... it's just not the same.
--
I much prefer printed docs to electronic ones, and I run two monitors. I think what most of the places turning to "e-manuals" really want to do is screw producing a serious manual altogether, and leace it to O'Reilly et. al., who will do better jobs anyway.
I still remember buying Autocad R10, it came with a hardcover manual the size of an encyclopedia and was about as info-packed. Now you spend $800 for Office 2kPro and all you get is a CD with a damn talking paperclip...
-cwk.
I have been a PC computer technician now for about four years, and if there's one thing I just can't stand about companies and their products is the "See the HELPMR.PDF file for details."
.PDF file when I can't get the drive workin' in the first place?!?
.PDF files are hilarious...just read them some time. You'll find questions like "What if my computer doesn't turn on after installing so-and-so?" "What if my CD-ROM drive or Hard Drive are unreadable after installing so-and-so?" How in the world would I be reading a .PDF if I can't get the computer working?!?
First off, if I have some in-depth question I need answered, I need to do some in-depth reading. I can't do that on the computer screen! My eyes would go blind if I studied an on-line manual to try and figure out what to do!
Second off, search modes for PDF files don't do crap when you need to figure out exactly what's wrong. Say I'm installing something like, oh, say a DVD Decoder card for a DVD drive I bought, but it's not decoding the movies. I need to figure out why. Well, open up good ol' AcroRead, type in the search field "Specs," and I'll have to wade through countless hits of the word "Specs," often not finding what I need. Well, I need to get more specific, but if I get too specific, I won't find what I'm looking for. Often times the only way I can find something is to do the same thing I do in any other printed manual: go to the index or table of contents.
And most importantly, and I STRESS this above the rest, If the computer doesn't work, I ***NEED*** printed documentation!!! I hate trying to install something new on someone's computer only to find that it hoses the computer, and there's no frickin' way to find out what's wrong because I have to get the computer on to find out what's wrong! What if I'm installing a new CD-ROM Drive? If it doesn't work, how am I supposed to get to a
I tell ya, some of those
If someone is buying a boxed product, there NEEDS to be a printed manual with at least semi-detailed instructions. You don't have to enclose a 300 page manual, but look at the TI-8x or TI-9x series of calculators. Not only do you buy the calculator, but you also get a nice 200 page paperback explaining how it works. Imagine if you bought the calculator and it came with "If you wish to get instructions, please go to www.ti.com/support/ti/8x and print the 200 page manual."
The advantages of online documentation are:
- Searchable.
- Copy and paste examples straight into the application.
- Follow the trail of purple links to see where you've been before (one could do this with books, but I don't like mutilating/marking them)
- Link out to relevant web sites.
- Download the latest changes and updates.
- Always available, your co-workers haven't 'borrowed' it.
- Results in cheaper software since I'm not paying for a dead tree.
Offtopic: The one thing that really annoys me about most documentation (printed or online), is that there is frequently no introductory text telling you what this product is for. It is irritating to find a piece of software called "GrokMaster 2000" and look at docs, and find the functionality of everything spelled out in minute detail, yet be totally mystified as to what the program is actually for.Slashdot monitor for your Mozilla sidebar or Active Desktop.
Speaking of which... what does the "SysRq" key (under "Print Screen" (which I have figured out)) do?
--
I hope paper manuals will never die. They really do provide a good way to read about the program. First, I don't have a Palm or laptop (yet, come on Birthday!) so when I fly or travel long distance in a car (like going home from college) I like to read. That's the obivious one. The not-so obivious advangate to paper manuals is the fact that I can read them while working on the very program. I like mult-tasking outside of my computer. I will keep the manual in my lap or on the side of my desk and work and read and generally get my work done easyily without having to look up in some help. I admit there are some nice things about electronic help. But for the most part I prefer a paper manual to anything else.
One thing you (person who asked the question) should keep in mind is a paper manual gives the consumers another reason to buy your product. I know when I was young I would warez games and stuff. Every game except flight simulators. That was because they didn't come with manuals if you pirated them. I bought those. Nowadays I've matured (at least I like to think so) and I buy all my software. I simply hate opening up a new game and just seeing a cd jewrel, no manual or anything except a registration card (Microsoft Motorcross Maddness). Paper manuals are a great way to add value to your package. I know I havn't bought a Microsoft game since I got ripped off like that. (That and I don't have Windows anymore). It seperates yourself from others when you give your consumers a good deal and treat them right.
Open Source, Open Standards, Open Minds
There's still the Toilet factor..(reading books and manuals on the bowl) and the Train factor.. It's just not convenient to fire up a laptop or even the PC to read a book or manual. Until HandHeld Ebooks which can read PDFs are a common thing, will print manuals be dead.
If you're not a Liberal in your 20's, then you have no heart.If you're still a Liberal in your 30's you have no brain.
It depends on the software, but I know it is nice to have bathroom library material for stuff you may not want to devote other real reading time to, but do want to pick up on eventually. I mean, hey the bathroom is a great place to brush up on windows API calls you may have used only sparsely before. Come to think of it, java or C++ library documentation would make good bathroom reading material too... Forvalaka
I like having printed manuals, their batteries do not wear out, and they can be taken anywhere.
Fight Spammers!
You can't take a CD into the john and read it. (Unless you take your notebook comuter also!)
I would rather have a searchable document any day, but I would also like to have the option of purchasing a paper manual. Guarenteed, my office is littered with unused manuals and stacks of unread instructions, but if I need them, then they are always around. One thing I hate, is I have so many old useless manuals (such as these books on Word Perfect v5.1 and Windows 3.1 user guides) cluttering my office. If I could have all these older documentation on CD-roms, I would be much happier. Perhaps someone should start a company to drop this older documentation onto Cds or into HTML. I would purchase it. Whats good about printed format? I can quickly go and look something up right away. If I am looking for the use or context of a command, and I cannot remember the exact command, (dont laugh..) then I can flip open a book and there it is. Ever tried searching for "That command that lets me ..." Both definately have their good parts, and definately both have bad qualities. Dell.com systems gives me the choice of how I want my documentation- I chose both.
/. is a commercial entity. goto slashdot.com