Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

The end user documentation I'm writing makes use of screenshots (and partial screenshots) to show the user what I'm referring to in procedural instructions for or conceptual explanations of the software.

However, I'm never quite sure whether to put the screenshot before the paragraph that refers to the screenshot or afterward. What is most readable? Furthermore, I'm not using figure captions. So, the problem might be that I have large sections of text referring to the screenshot at all. Maybe the caption should explain the screenshot and the text shouldn't directly refer to it.

What are some practices in technical writing that would help me here?

share|improve this question

3 Answers 3

up vote 8 down vote accepted

If a reader follows a reasonable path1 through your documentation, there should never be a point where he's looking at something incomprehensible. This applies to text, code samples, diagrams...and screen shots. Therefore, unless the structure of your document itself provides this (e.g. through section titles and a consistent format, like in a catalogue), you should always have some explanatory text before the screen shot to provide context.

However, this principle applies to text too -- you don't want to have a page of text describing stuff that will only make sense after someone sees the screen shot, either. So in my experience the norm is: text that sets the stage, then the screen shot, then details that refer to the screen shot.

This is true with or without figure numbers and captions.

1 At minimum (for non-reference doc), starting at the beginning and reading through. But also consider the case of someone who looks something up in the table of contents and jumps there, and, if applicable, the use of your documentation in online context-sensitive help.

share|improve this answer
3  
Definitely this. Tell the reader "You're looking at the screen of...", show it and then proceed with "Notice the following..." –  SF. Jun 14 '13 at 23:35
    
Awesome -- thanks. "text that sets the stage, then the screen shot, then details that refer to the screen shot." That's helpful. –  Matthew Rodatus Jun 17 '13 at 15:57
1  
This is the answer. A screenshot is just a (somewhat) pretty picture until the reader knows why they are looking at it. Many screen shots have a lot of details in them and the reader needs to be guided as to what to look for and in what order. The designer (and you) know why the screen is organized the way it is. Tell the user so they know how to look at it as well. Perception is all about setting expectations and frames of reference. –  Joe Jun 19 '13 at 17:51

1) Put the descriptive text first, then the screenshot immediately afterwards. We read down.

In the Print dialog box, click Export to PDF.
[SCREENSHOT of dialog box]

2) You may or may not need a caption, but you should at least label each screenshot. Fig. 1, Screen B, Ralph, something. That allows you to refer to it elsewhere in the text.

share|improve this answer

An introductory text should always come before the screenshot that you are about to display. This will help the user to get an idea of what is about to be displayed in the screenshot.

Then you can definitely provide the descriptive text for what exactly is happening in the screenshot for better understanding of the user.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.