Fog Creek Software
Discussion Board

If nobody reads manuals...?

do we still have to write them?  In how much detail? 

What sort of manuals/help files do the Fog Creek products have?

Boofus McGoofus
Monday, April 19, 2004

CityDesk has a very comprehensive manual but it's 100% electronic. It has two types of content:

* Reference material you can use to learn about a particular document on-demand
* Tutorial material that shows you around enough to get you started

FogBUGZ has a lot less documenation. There's the reference material, but only a few chapters on a few specific topics, and there are also some more narrative articles about bug tracking in general so you get the idea of how it works.

I can't say I really know what the right thing to do is in terms of manuals, but we don't get any complaints about the thin FogBUGZ documentation -- maybe it's self explanatory -- and we do get a lot of compliments on the CityDesk documentation, so somebody must be reading that.

I think the ideal model for software documentation would be:

(1) Introductory material that teaches you the underlying concepts -- what I call the Program Model. This can be done with written tutorials or online videos. Depending on how complex the domain is it can take 10 minutes (like CityDesk's tutorial) or as much as several weeks (for CAD and high end accounting products).
(2) Once you know the underlying concepts, the program should be self-explanatory enough that you can figure out how to do things without consulting documentation. All that step by step documentation (move the mouse over the OK button, then, without moving the mouse, press and release the *left* button under your index finger) is just wasted verbiage for most people
(3) And there should be an index of reference material you can consult when you want to learn one of the program's advanced concepts.

This is mostly what we accomplished with our products, but I can't say we spend too much time worrying about it or surveying our users.

Joel Spolsky
Fog Creek Software
Wednesday, April 21, 2004

Just to chime in on this, I am a technical writer and I consider documentation to fall into the 80/20 rule of software.

I find it very frustrating that people don't read the manuals. For some reason it is just not in most of our natures to hit F1 when we have a problem.

I can also sympathize with users because there are many times when I have been using some software, pulled up the help and found the answer to my specific question not there (that includes CityDesk too). I believe that this, in part, has a hand in the aversion of most to not use the provided documentation.

So to answer your question, should you include docs, Yes. Because at some point someone will be up late at night and have a problem with the software. If they are not able to contact technical support they will have to resort to fumbling the docs. If they aren't there, you have just cost your customer a lot of productivity and probably cheesed them off in a major way.

Wednesday, April 21, 2004

It's not in "our nature".  We've been trained to do that by the computer industry of a period of years and years.

When you press F1 sometimes nothing happens.  Sometimes you get an empty help file, or an error message.  Usually you get a help screen full of incredibly unhelpful information, with sentences like "Foobaz: Check the foobaz checkbox to enable the foobaz feature".  Ok, that's really insightful...

I can count on the fingers of one hand the number of programs for which I'd describe the documentation as "good" or "excellent".

Sometimes the documentation is good, but it's in a lousy form.  The Adobe Illustrator manual is pretty good -- if you like sitting down to read a 700-page book cover-to-cover.  There's an online version, but navigation and searching is really bad, so I can't stand using it.  It's faster to grab the book off the shelf and flip through it.

We've learned that, on average, trying to use online help is a time-losing proposition, not a time-saving one.  It's a last resort.  A chicken-and-egg problem, perhaps, but not one you can really blame users for being stuck in.

Wednesday, April 21, 2004

Is there a downside to have a question mark button on every panel, that brings up a manual page (with a screenshoot of that panel) with detailed help for every single widget/control on that panel?

I've only seen a couple apps that do this, and I've found it very useful.

Wednesday, April 21, 2004

I agree that docs can be a complete mess a considerable portion of the time. Of that I can agree.

Documenting every widget using "What's This" help (the question mark in the corner of the dialog) can be beneficial in some situations.

The thing is about Docs is there can really never be enough of it. You want users to have as much options as possible. Everyone learns differently and if you can cover every angle you got a better chance of actually assisting the user. This is an ideal of course, striving for this is a good objective.

Wednesday, April 21, 2004

_I_ read manuals.  When people ask me for help with a tool, the first question I usually reply with is "What does the documentation say about it?".  It's usually there, so the co-worker learns something and I'm bothered less often!  SCORE!

A good example of what I consider excellent documentation is the Windows client to the MSDN library:  with its integration with the IDE, you can hover any .NET method in VS.NET,  hit F1 and get what you want.  You can start typing the method name in the index and it will jump to the closest hit.  Or you can type the class name, dot, the method name.  Or you can type the namespace, dot, the class, dot, etc.  It has great searching and having the "show this topic in the table of contents" button is great for browsing related topics, especially when you're not sure what something is called.

The best feature, though, I would say is the "Click here to send feedback on this topic".  I use it every time the documentation isn't immediately clear on something and, about half the time, within a few weeks, I get a personalized e-mail thanking me for my suggestion for improvement.

All documentation should have feedback links:  all you need to build is a mailto hyperlink that stuffs the subject line with the topic identifier.  If you have FogBUGZ, it's even cooler if you set the feedback's e-mail address to one used by FogBUGZ for external submissions.

Also, with NDoc, RoboHelp or even MS's SDK, it's so easy to create .CHM files, nobody should have an excuse to not create them anymore.

Using help is what makes it better:  it's the same feedback loop you should have with your software.  In fact, documentation _is_ part of your software, right?

Wednesday, April 21, 2004

I have to say that I am more prone to hitting Google these days, rather than the help files.

Michael Joyner
Wednesday, April 21, 2004

The "What's this" question mark can be very useful, if it tells you what the particular control does and why you might want to adjust it. All too often, if you want to find out what a slider called "Interocitor strength" does, it tells you "This slider lets you adjust the strength of the interocitor" Gah!

Thursday, April 22, 2004

A very, very long time ago I had too choose a wordprocessing package for writing my dissertation. Even at that time their was a large "anything but microsoft" contingent at the university, and the going mantra was "Don't use Word, use LateX, you can not do decent Equations in Word". Now don't get me wrong, LateX can produce some damn fine output and the structured approach is nice, but I really didn't feel like stepping back into the stone-age UI wise. So I did something no man had ever done before: Read the Word manual (this was Word 5.1 on the Mac). Sure enough, I found tons and tons of features nobody had ever heard of, e.g. how to do formulas without the Equation applet, how to do pixel positioning macros for the formula items etc.
When shown the final result, none of my collegues believed that this was a Word document, since they where used to seeing every word document with formulas that where hacked out of granite by a five year old with a tremor.
Reading a manual can be a big plus.

(Unfortunately modern manuals seem often to be pretty poor)

Just me (Sir to you)
Thursday, April 22, 2004

If you're developing something that lacks a graphical user interface (think libraries, drivers, server services, etc), a manual is critical.  If the user has no interface, they have nothing that provides them with intiutive clues.

We make pretty large manuals for our products.  We recently stopped giving out printed copies, but we still make "real" manuals.  We just distribute them in PDF.

My personal rules for a product manual:

- Give a printed copy, or put it in a format that's easy to print as a "book".  Windows Helpfiles are not easy to print.  Use a PDF, or something similar.

- Make it easy for the user to use while they're actually using the product.  This can be a Windows Help file, or even a PDF with really good bookmarks.  It has to be esily searchable.  Preferably with some sort of index.

As you can see, these goals can be mutually exclusive.  The best thing you can do is use a tool that automatically generates both a PDF, and a Windows Help file.

For an end-user application, a "manual" isn't as critical.  The user interface should be intuitive enough to use.  However, you should still provide some kind of "Readme 1st" or "Getting Started" guide for the total novice.

Once the user starts using the application, they may occasionally need help.  My personal favorite is the "What's This?".  When I don't know what an option will do, it's the quickest way to find out.  But if you make "What's this?" menus, for the love of god make them actually anser the question (what IT is).  Nothing pisses me off more than clicking "What's this?" for an option and seeing:

"Checking this box will enable option X.  Unchecking it will disable option X."

Myron A. Semack
Thursday, April 22, 2004

I love my iBook, and I hate Apple for instigating the trend of making things look "easier" by not including a manual.

I must use more toner than anyone else around here. The first  thing I do when I install new software is print the manual and put it in a binder. Then I get little Post-it notes to mark important pages that I'll be coming back to. Good thing I can work with 2-up, duplex, or I'd be killing even more forests.

Ham Fisted
Thursday, April 22, 2004

One problem I face with regard to manuals is the crummy office I work in, which along with those of 95% of the corporate world, is wholly inconducive to even the amount of concentration required to carry a thought from one sentence to the next.  Loud HVAC noises, unobstructed chit chat noise, bad flourescent lighting, stuffy recycled air, sealed creapy-colored low-emissivity windows when any windows at all, wafting microwave popcorn smells, cheap desk chairs, oppressively tiny cubicle.  There's no way I could read much more than a JOS post in this kind of environment, let alone 649 pages of hastily scribbled technical manual.

(And I'm a programmer, so imagine how much this environment effects my actual job productivity.)

Can't Concentrate
Thursday, April 22, 2004

"There's no way I could read much more than a JOS post in this kind of environment, let alone 649 pages of hastily scribbled technical manual"

Not all docs come in 649 page manuals. There is also context sensitive help. While flawed it is still more helpful than sifting through a paper manual. And rememeber the search function is there for a reason too. Again, with docs YMMV.

Friday, April 23, 2004

*  Recent Topics

*  Fog Creek Home