MadCap Software Forums

What do you folks think of this article, and the one linked from it?

http://www.soltys.ca/coredump/2009/07/d ... sense.html

I'm still trying to make sense of it.

Generally speaking, I tend to use screen shots only in cases where I add more information to the image. For example:

- I use screen shots as the basis for image maps which link to popups or tooltips that provide more information to the user. This way, the user doesn't have to know what a screen element is called to find help about it; all they have to do is click on the picture. This is helpful in cases where the UI has an icon that the user may not recognize - it's all well and good to identify it by name in your documentation, but if the user doesn't know the name it won't help them.
- I also use screen shots with callouts when I want to draw the user's attention to a specific part of the interface.

Both of these I use sparingly. If I can describe a tool or what the user should do clearly without an image, I do so. I put in the screen shots as described above when the explanation I have to provide to the user becomes too cumbersome.

I think there is more to it than the articles cover, mainly because the original article only looks at a very specific case. The fundamental question I'd ask is "Is there any reasonable chance or intention that the documentation or parts thereof will be consumed without having the application available?"
If the answer is yes, I'd definitely include screen shots, because the availability of the application cannot be guaranteed. A yes is also given when the help is to be published on the web for a desktop app. The next question would be "Will the GUI be localized?".
If yes, opting for screen portraits may be the better option then for some cases.
Then also, who will be using this documentation. If the audience is typically not technically/computer savvy they may find pictures more helpful.
How is the help to be hooked into the application? If the goal is to provide embedded help I'd definitely not include any screen shots, because there is just no space.
And then it is also the type of documentation. How to topics can typically do well without screen shots, anything used for reference or general overviews probably should have some images.
And finally, pictures, animations, and videos enhance the entertainment factor. People will consult the help more often if there is some kewl stuff to watch, if using help is fun rather than torture.
Finally, pasting entire screen or window shots in the topics is not only a space problem, but also as confusing as the actual GUI. I typically partition the forms into sections and deal with individual sections, such as title bar, menu bar, entry fields / work space, button bar.

In my case, I'm more apt to include screenshots for the following reasons:

• I like to print manuals and read them when I'm away from the computer.
• What you call a screen may not be what a user calls the screen, so it helps if the picture matches what they see on the screen.
• The appearance of a screen may change depending on what is selected, what features the user is allowed to use, how the user got to the screen, and so on. Including screenshots at certain points not only helps the user make sure they're in the right spot, but can be a great marketing tool if the user sees a feature on a screenshot that they didn't pay for and may tempt them to buy it.
• Some users don't have the necessary screen real estate to view the help side-by-side with the application, so the argument that the user will use the help while using the application doesn't always fly as a reason not to include screenshots.

All that said, I try to only use the screenshots in the "about" section of the help ("About the Main Screen", "About the Configuration Screen"). In the task sections, I just list the steps the user has to follow to perform the action, but anywhere it references a screen by name, I include a hyperlink back to that screen's "about" page.

RamonS wrote:I think there is more to it than the articles cover...

I pretty much agree with everything RamonS said. In my case, we haven't done embedded help, so a couple of my bullets don't apply. However, if you do have embedded help, I think you should also include a printable version that does include screenshots so the user can print that manual, if desired, and read it away from the application.

*grins*
I disagree. Emphatically.

I particularly don't like the implication (in the article) that we would avoid images because they are annoying given all the format shifting and layout hurdles we have to jump through. “This is a particular problem for those using XML-based tools, especially DITA, which can be inflexible in the way they handle graphics.” So, the capabilities of our tool are going to shape what makes good documentation? i.e. "Hmm. Images are hard. So... maybe we don't need them so much anymore..."

My thoughts:
1. I feel that good software documentation is portable: easy to read and understand whether a copy of the program is available or not.
2. I feel that good documentation reaches people who do not like words as much as I do. People don't read, much, anymore; we jump directly to visual queues, and I sometimes feel that I am the only one left in the universe who reads more than the first sentence of each paragraph in a lengthy e-mail.
3. I feel the English language has too much ambiguity and weakness built in. Sure, you can overcome that with painstaking sentence construction, but painstakingly constructed sentences are sometimes longer and even less likely to be read.
4. Software interfaces rely on a series of metaphors. Does your "Save" button still looks like a 3.5 inch floppy disk? Do you still use the term "radio button"? Will we still being calling it "scrolling" five years from now? These metaphors and interface elements are still evolving and are understood differently by different people or in different contexts. An image removes this ambiguity.
5. When teaching anything, the old triple-play is still good: “Tell them, show them, and then tell them what you showed them.”

Disclaimer: My target users' sophistication ranges really widely. I expect that readers of my how-to guides have completed high school, but some have not. Other readers of my documentation have advanced degrees, but they tend to think narrowly down their own path. Some of my users can read and write Spanish at the college level, but understand English at a lower level.

For some documentation, images are more essential than words.

And, for many of our clients' needs, full video with audio narration is starting to take over. Ten times as many people will sit down and watch my videos than will browse my help system.

beagley wrote:I particularly don't like the implication (in the article) that we would avoid images because they are annoying given all the format shifting and layout hurdles we have to jump through. “This is a particular problem for those using XML-based tools, especially DITA, which can be inflexible in the way they handle graphics.” So, the capabilities of our tool are going to shape what makes good documentation? i.e. "Hmm. Images are hard. So... maybe we don't need them so much anymore..."

From a purely theoretical standpoint, I agree. From a practical standpoint, I have a budget, I have a limit to the number of writers I have, how much time before release, how many projects are on our plate, etc. Sometimes the limitations of our tools *create* practical limitations that we'd otherwise avoid. For example, the kinds of linking that the new Relationship Table feature in v5 offers could be done manually, but in my projects, we don't do that because we don't have the time. Similarly, we do not have the time or resources to generate a PDF of every online help topic, and link it with a little "printable version" icon so a user can easily grab a PDF for on-the-go reading. If Flare automated that, on the other hand....

1. I feel that good software documentation is portable: easy to read and understand whether a copy of the program is available or not.

I agree with much of the rest of your points, but this I cannot -- I think documentation should be appropriate to the context in which it will be used. Online help (for example, a CHM) is invoked from the application, and I think that, for the most part, screen shots are a bad idea there. Not just extra work; but rather extra work which actually makes the help less helpful. I think graphics should be used sparingly, where they will be most helpful (such as flowcharts, etc.). Screen captures of course have their place in a more paper-oriented manual, where I would expect to see heavy use of them.

Oh, I agree SO VERY MUCH with beagley!!

We are currently working on a new concept for our usr documentation. We sketched different types of help - depending on the situation.
E.g. we have topics describing what entry fields and buttons of one specific GUI do - that's the help you usually get after pressing F1 inside the application. In that case we will have pictures only if necessary (cannot think of a case like that), simply because the real GUI is available in that moment.
There's also another type of topic which is describing concepts of the application. Yet another type is giving step-by-step algorithms to fulfil a specific task.
With those two types pictures make a lot more sense, because that's the type of documentation that is either printed and stored in "real" files in shelfs (step-y-step) or being read in a quiet room (concepts).

One more argument for pictures especially in long texts like manuals or concept descriptions: Psychology (motivation).
Just imagine your boss tells you that from now on you will have to perform a specific task with the application. You find a chapter in the manual about that theme. You look at that chapter and it's pages and pages and pages of text ... pure text ... demotivating, that ...

It's our job to get the information to the user. If that means in an easy-to-consume way, then so it shall be.
E.g.: Enumerations are sort of forbidden in a normal sentence, but should be displayed in a list with numbers or bullets - telling the user "Enumeration here" ... the pictures are the same category.
To say it with Amendt: If a user has to "read", he's off ...

Andrew wrote:Online help (for example, a CHM) is invoked from the application, and I think that, for the most part, screen shots are a bad idea there. Not just extra work; but rather extra work which actually makes the help less helpful.

One good way around this is to hide the image in a toggler or dropdown. Most of the time in online help, users won't need to see a screenshot because the UI is right there, but sometimes they will (for example, if the user has followed some links in the help they may no longer be in a topic that is related to the screen where they invoked the help, so the UI does not match the topic anymore). Putting the image in a toggler allows you to keep it out of the way for users who don't need it (that way they are less likely to have to scroll) but means that those who want the image can get it with a mouse click. This way you can meet the needs of both types of readers.

KevinDAmery wrote:One good way around this is to hide the image in a toggler or dropdown.

Works for online help, but not for printed ...

i-tietz wrote:

KevinDAmery wrote:One good way around this is to hide the image in a toggler or dropdown.

Works for online help, but not for printed ...

I was going to say, we use LOTS of PDF ouput here. That is a nice solution but won't work for printed material.

KevinDAmery wrote:One good way around this is to hide the image in a toggler or dropdown.

In Flare v5, the thumbnail functionality is much improved and can make an excellent compromise for help files, albeit not so great for PDF.

Sure it will work in print: what you do is put the image in a paragraph that is set to be hidden or shown by a toggler, then use a condition on the toggler hotspot to make it appear in Online outputs only. When you do this, the image automatically appears in print outputs and the toggler text is conditioned out. I use this method here all the time.

KevinDAmery wrote:One good way around this is to hide the image in a toggler or dropdown. Most of the time in online help, users won't need to see a screenshot because the UI is right there, but sometimes they will (for example, if the user has followed some links in the help they may no longer be in a topic that is related to the screen where they invoked the help, so the UI does not match the topic anymore). Putting the image in a toggler allows you to keep it out of the way for users who don't need it (that way they are less likely to have to scroll) but means that those who want the image can get it with a mouse click. This way you can meet the needs of both types of readers.

I appreciate the suggestion, and yes, I've done that before. It certainly helps in terms of reduced scrolling and not having enormous images pop out and take over a topic entirely. It's especially useful if you have to include the screens in the first place for single-sourcing a print version. It's also a matter of work -- every screen cap you add is extra work, and then even more to add it to a drop-down. Our current large project has some 7000+ topics. It's a major pain to add and then update a couple of thousand screen shots or more. Sparing use of images makes a lot of sense. Our schedules and resources are limited. A while back, we used to have little movies attached to all of our step-by-step procedures, but the project grew, and we didn't have the resources to update them, so we had to remove them.

In one of our smaller projects, we use images more frequently, especially in such areas as introductions to the product, descriptions of how chart and graph settings work, etc.

KevinDAmery wrote:Sure it will work in print: what you do is put the image in a paragraph that is set to be hidden or shown by a toggler, then use a condition on the toggler hotspot to make it appear in Online outputs only. When you do this, the image automatically appears in print outputs and the toggler text is conditioned out. I use this method here all the time.

Yes - and that means:
"optional" images only for online output,
BUT: "compulsory" images for print output.
That's what I was writing about ... no solution of the problem for print output.

KevinDAmery wrote:

Andrew wrote:Online help (for example, a CHM) is invoked from the application, and I think that, for the most part, screen shots are a bad idea there. Not just extra work; but rather extra work which actually makes the help less helpful.

One good way around this is to hide the image in a toggler or dropdown. Most of the time in online help, users won't need to see a screenshot because the UI is right there, but sometimes they will (for example, if the user has followed some links in the help they may no longer be in a topic that is related to the screen where they invoked the help, so the UI does not match the topic anymore). Putting the image in a toggler allows you to keep it out of the way for users who don't need it (that way they are less likely to have to scroll) but means that those who want the image can get it with a mouse click. This way you can meet the needs of both types of readers.

That depends on your audience. Someone who is hopelessly confused by seeing a screen shot in help next to the application most likely will be challenged by the concept of togglers. And that assumes that they find the help to begin with.

i-tietz wrote:

KevinDAmery wrote:Sure it will work in print: what you do is put the image in a paragraph that is set to be hidden or shown by a toggler, then use a condition on the toggler hotspot to make it appear in Online outputs only. When you do this, the image automatically appears in print outputs and the toggler text is conditioned out. I use this method here all the time.

Yes - and that means:
"optional" images only for online output,
BUT: "compulsory" images for print output.
That's what I was writing about ... no solution of the problem for print output.

Well, if you really don't want the image for print output you can conditionalize it too. (Although the norm is to show the image in print because the user may not be in front of the UI, so I'm not really sure what the problem is here.)

RamonS wrote:

KevinDAmery wrote:

Andrew wrote:Online help (for example, a CHM) is invoked from the application, and I think that, for the most part, screen shots are a bad idea there. Not just extra work; but rather extra work which actually makes the help less helpful.

One good way around this is to hide the image in a toggler or dropdown. Most of the time in online help, users won't need to see a screenshot because the UI is right there, but sometimes they will (for example, if the user has followed some links in the help they may no longer be in a topic that is related to the screen where they invoked the help, so the UI does not match the topic anymore). Putting the image in a toggler allows you to keep it out of the way for users who don't need it (that way they are less likely to have to scroll) but means that those who want the image can get it with a mouse click. This way you can meet the needs of both types of readers.

That depends on your audience. Someone who is hopelessly confused by seeing a screen shot in help next to the application most likely will be challenged by the concept of togglers. And that assumes that they find the help to begin with.

Uhh, if they can't find the help I'm not sure what design for the help will help them? Hey, maybe I could put a topic in the help system about how to open the help system - would that help?

KevinDAmery wrote:

RamonS wrote:That depends on your audience. Someone who is hopelessly confused by seeing a screen shot in help next to the application most likely will be challenged by the concept of togglers. And that assumes that they find the help to begin with.

Uhh, if they can't find the help I'm not sure what design for the help will help them? Hey, maybe I could put a topic in the help system about how to open the help system - would that help?

Surely users will find the help by clicking on a button saying "Help" or by a button in the app window that shows a question mark.

Once they have the help open:
We INDEED HAVE a button in the HTML Help buttonbar saying sth like "Help to Help". The topics in that part of the help contain the handling of dropdowns, quicksearch, toolbar and notation but also things like what information you find in what type of topic (described it in earlier post).

Im surprised to hear you haven't got anything like that?

I have one about how the help system is organized and where to look for certain types of topics. But I don't see much point in adding content about "how to open this help system" (if you've got it open, you don't need to be told how to open it, and if you can't find how to open it putting the directions inside won't help much - that's probably better served by a tooltip on the main UI).

As I said: It needs a button saying "Help" or a symbol with a question mark with the tool tip saying "Help".
We have an organisation in Germany that evaluates documentation in an annual contest. The first thing they look at is the product and not the help or the manual ...
GUI design is a part of the job of a tech author.

Interesting thread, thanks!
I tried the route of no screen shots for a few years. One reason was time constraints - marketing would only get the final imagery (icons, logos, etc.,) to development at the last moment, and the screens were then incorrect. However, I did buy into the idea that duplicating a screen when it's already there, and the user pressed <F1> for help, was a space-waster. Also, the help file was a fraction of the size, which helps download size when when doing patches or updates online.
Bottom line, for whatever reasons, users hated it, even in the procedural sections. I got development to give me a mode without icons in window headings, and I ended up with only a few screens I had to change at the last minute.
At the same time, I'm using togglers to hide and show screens, so for some users who don't need the screens, they are not there.

Great discussion.

I'm chewing over the "yeah, but that would take too long" arguments against copious screenshots. At first, I wanted to reiterate: Limitations, such as time or the tools you use, should not be a factor in defining what makes up the BEST documentation for a specific circumstance.

In other words, if a piece of documentation is improved by images, that's an end-of-line statement. No argument about time, tool limitations, or a difficult workflow with developers can change the statement, "This document would be easier to understand and more user-friendly with images." The two topics are unrelated.

But then I thought of one way in which they ARE related: The best documentation is also AVAILABLE. Finished. Public. So, obviously, if doing a good job on images takes too much time, then the images are NOT improving the documentation. Because they might keep the documentation from reaching the public!

Like you guys, I've spent a lot of time trying to accelerate my screenshot workflow... setting up the data for the software, grabbing the images and formatting them quickly, keeping a good serial number system for easy updates... it helps. But to update a single screenshot, I need to fire up the product, then Parallels, SnapNDrag, GraphicConvertor, Omnigraffle, and then Flare. It's an astonishing dance, but learning a few shortcuts has gotten the whole process down to about 10 minutes, with maybe another minute for each additional image. Minutes can sure add up quickly, of course.

The argument about "compulsory" images for print vs. toggles and icons for online reminds me of an old quote: "Paper is actually a terrible medium for information storage and dissemination, when compared to electronic. And electronic is a terrible medium for reading and absorbing information, when compared to paper."

Isn't it poetically odd that we read a printed PDF that contains screenshots of a computer screen? Which itself contains a metaphor for data or (health information, in our case) that came back out of the physical world? I often sit back and chuckle at the number of LAYERS between my eyeballs and the information I am actually reviewing... the number of translations, the distance between reality and my brain.

beagley wrote:Isn't it poetically odd that we read a printed PDF that contains screenshots of a computer screen? Which itself contains a metaphor for data or (health information, in our case) that came back out of the physical world? I often sit back and chuckle at the number of LAYERS between my eyeballs and the information I am actually reviewing... the number of translations, the distance between reality and my brain.

cool ... any chance of getting some of whatever you inhaled?

beagley wrote:In other words, if a piece of documentation is improved by images, that's an end-of-line statement. No argument about time, tool limitations, or a difficult workflow with developers can change the statement, "This document would be easier to understand and more user-friendly with images." The two topics are unrelated.

But then I thought of one way in which they ARE related: The best documentation is also AVAILABLE. Finished. Public. So, obviously, if doing a good job on images takes too much time, then the images are NOT improving the documentation. Because they might keep the documentation from reaching the public!

This is one of those things that varies depending on your situation. For example, if your help is stored on your servers and provided to the customer over the internet, then you have the flexibility to update the help whenever required: this would let you release the product with text-only help as soon as the product is available, then add the screen shots in over time. OTOH, if the help is installed on the user's machine you pretty much have to have the help ready to go at the same time as the code is released to manufacturing (unless your product supports automatic updates, of course - then you might be able to arrange to put an updated version of the help in along with the code updates).

MikeKatz wrote:I tried the route of no screen shots for a few years. One reason was time constraints - marketing would only get the final imagery (icons, logos, etc.,) to development at the last moment, and the screens were then incorrect. However, I did buy into the idea that duplicating a screen when it's already there, and the user pressed <F1> for help, was a space-waster. Also, the help file was a fraction of the size, which helps download size when when doing patches or updates online.
Bottom line, for whatever reasons, users hated it, even in the procedural sections. I got development to give me a mode without icons in window headings, and I ended up with only a few screens I had to change at the last minute.

And that's another major consideration. We can all theorize about what makes the best help until we're blue in the face, but at the end of the day the only thing that really matters is "what do the customers find helpful?" If the customers tell support that they want screen shots in the online help, refusing to give it to them because we believe "online help shouldn't have screen shots" sounds like a classic case of "developer arrogance" (to use one of RamonS's favourite phrases).