The Joel on Software Discussion Group (CLOSED)

A place to discuss Joel on Software. Now closed.

This community works best when people use their real names. Please register for a free account.

Other Groups:
Joel on Software
Business of Software
Design of Software (CLOSED)
.NET Questions (CLOSED)
Fog Creek Copilot

The Old Forum

Your hosts:
Albert D. Kallal
Li-Fan Chen
Stephen Jones

Do screenshots help make user documentation better?

I've been going through some rapid release cycles on a couple of my applications, and the GUI's of these apps tend to change with each iteration--sometimes a lot.

I try to provide up-to-date user documentation with each release, but a real time sink is including screenshots. I feel I have to update screenshots with each new iteration, otherwise the docs will look out of date.

Is it even necessary to include screenshots? Are they more useful for marketing purposes than documentation purposes? I certainly update my website with new screenshots each time I do a new release, but that's no problem--just a couple of shots. By contrast, including screenshots of all of the major features/functions of my apps in the user docs is cumbersome--and updating it is even more cumbersome.

It would be my preference to update the user docs' text, but eliminate (or minimize) the use of screenshots. How do others handle this?
Don't like screenshots
Tuesday, October 31, 2006
If you had asked a week ago, I'd have probably said no.  Today I'll say not usually.

Just last Saturday I read how to do something and the guy posting it didn't just give the usual Edit->Options: WidgetConfig=4...etc...  He had few well cropped screenshots detailing the operations.  It made a world of difference because the verbal description would have been very confusing.

I'd say that if the problem is best solved by showing someone, "click here, here, then here."  Then a screenshot may be more appropriate.

Showing a screenshot to access the file menu to show clicking on the print button is just padding the documentation unless you have the most basic of users.
Lance Send private email
Tuesday, October 31, 2006
If you are updating your apps on a frequent basis, you need an automation help-authoring tool that can facilitate your efforts.

To achieve this objective in a timely fashion, I would strongly recommend the DR. EXPLAIN software. It sounds like this would be the perfect help-authoring tool for what you are doing. Dr. Explain automates alot of the work.

Have your company fork out the money for a license.

DISCLAIMER: I am in no way affiliated with the Dr. Explain software, it's business or its personnel.
Brice Richard Send private email
Tuesday, October 31, 2006
Depends on the audience.

For anything REMOTELY close to a "typical" user I would say OH MY GOD YES. End users don't read the words. Well, you're hard pressed to have end-users pick up the manuals at all, so anything you can do to make it easier for them is much appreciated.

If your "audience" is more techy, like Visual Studio 2005 developers installing an add-on to allow some fancy refactoring ability, then you'd be much more likely to get away with a screenshot-light manual.

But even those people find the screenshots helpful. Sort of a "am I in the right place" kind of confirmation.

The follow up question is "do I really need to keep them up to date with each release?" to which the answer is YES. Having the WRONG screenshot in the manual is much worse than having none at all.
BradC Send private email
Tuesday, October 31, 2006
What Lance said.

For online help, most screenshots just waste monitor real estate. The user is looking at the UI - why would they want a picture? The exception is for tasks more complex than clicking and typing.

For printed or for-print documentation, screenshots are probably a good idea because people may be reading them away from the computer.

Where an online help is placed on the web as a sales tool, it's also useful to have screenshots.
Documentation Doctor Send private email
Tuesday, October 31, 2006
A picture speaks a thousand words...
Another Anonymous Coward
Tuesday, October 31, 2006
"By contrast, including screenshots of all of the major features/functions of my apps in the user docs is cumbersome--and updating it is even more cumbersome."

Hard work making a professional product, isn't it?

It's all part of improving your product. Write the code, test the code, rewrite the manual, redo the screenshots, spend all the extra money you're going to earn from new customers.
Tuesday, October 31, 2006
depends. I kinda like doing screen shots or mock-ups as users only have to look at pictures and not read documents. Which they seem not to do!
Patrick from an IBank Send private email
Tuesday, October 31, 2006
Definitely yes.  "A picture is worth a thousand words."

End users do not read the documentation?  On the other side, sometimes, the written documentation is not up to snuff.  I have read too much alleged documentation that seem to exist only so that it can be said that there is documentation.

It is particularly nasty with software libraries and the like.  Giving the function prototypes just is not enough.  What are each of the parameters for?  What are their permitted values?  Even, what exactly does this function do?  All too often, this basic information is missing.


Gene Wirchenko
Gene Wirchenko Send private email
Tuesday, October 31, 2006
In agreement with Patrick.  Screenshots appeal to those of us who want to get the job done without having to dedicate a solid hour to sifting through documentation.  Q:  How many of us have actually read the MS Office user's manual?  Anyone?  Intuitive (or repetitive) design is the reason, but there may be one time when you'll need to know how to fill a template.  Flip through a manual, find a picture of a template, and voila!  Everything you need will be on those few pages. 

Of course, there are those people out there who feel the need to ingest every piece of information prior to using a product.  A screenshot to them will be nothing more than a sense of familiarity when they are eventually presented with that screen.
Drew Send private email
Tuesday, October 31, 2006
What does my app do?
You have only got 2 seconds...

See how useful screenshots are?
Yoriz Send private email
Tuesday, October 31, 2006
Is there any reason why you can't generate them automatically?

That way you just run the program in "screenshot" mode after you change the GUI.
Jimmy Jones
Tuesday, October 31, 2006
I think Yoriz just beat out Andy Brice for the world's most nichey software product!

I say that with respect. More power to you both.

I wish I got to use words like "frustum" in my projects.
Greg Send private email
Tuesday, October 31, 2006
Yoriz: I see only an obscure "dialog" of sorts, and that's the last item on the page!

You do have images, but they aren't screenshots.

That's a very clear, website with very clear diagrams, images and descriptive text, but it's /not/ screenshot heavy.
Arafangion Send private email
Tuesday, October 31, 2006
I think that screenshots are very useful in documentation.

But also important is to do things like make sure the text of the documentation matches the actual words used in the program! And that the section dealing with Edit menu commands includes those commands, and not half the commands from some other menu, leftover from the way things used to be in version 0.41.
Tuesday, October 31, 2006
Yoriz's cone-making app is pretty cool.
Tuesday, October 31, 2006
Yoriz - that's not user documentation! (Which is why that's a very good example of a effective use of screenshots.)
Documentation Doctor Send private email
Wednesday, November 01, 2006

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
Powered by FogBugz