Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs

Dashboard
Notifications
Mark all as read
Q&A

In end user documentation, should screenshots come before or after the text that references them?

+2
−0

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 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?

Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/8164. It is licensed under CC BY-SA 3.0.

0 comment threads

2 answers

+2
−0

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.

Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+1
−0

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.

Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »

This community is part of the Codidact network. We have other communities too — take a look!

You can also join us in chat!

Want to advertise this community? Use our templates!

Like what we're doing? Support us! Donate