Use graphics to clarify your subject matter. A graphic can be a
screenshot, diagram, graph, chart, or any graphic element. You can use the
following types of graphic:
- Formal graphic
-
A formal graphic is numbered and has a caption. A formal
graphic usually appears in the table of contents of a manual.
- Informal graphic
-
An informal graphic is not numbered, and does not have a
caption. An informal graphic does not appear in the table of contents of a
manual.
Use the following guidelines to include graphics in your material:
-
Use graphics to provide additional technical information that
is not provided by the text. Do not repeat existing text information in graphic
format.
-
Where necessary, use a complete sentence to introduce a
graphic. Use the introductory sentence to put the graphic into context.
-
Consider the type of material you are writing, and how users access the material, before you include screenshots of the application.
There are different considerations for online Help and printed manuals. See the
following sections:
-
Use a formal graphic when you want to refer to the graphic
from other sections of the document.
-
Use a formal graphic when you want the graphic to appear in
the table of contents.
-
Use a formal graphic for a screenshot at the start of an
applet online Help manual. You do not need an introductory sentence for a
screenshot of an applet at the start of an applet manual.
-
Assign an appropriate caption to a formal graphic that
matches the style of other captions and section headings. Use title
capitalization rules for graphic captions. Position the caption above the
graphic.
-
Use an informal graphic when you do not want to refer to the
graphic from other sections of the document.
-
Use an informal graphic when you do not want the graphic to
appear in the table of contents.
-
Use an informal graphic for graphics that occur in text
blocks, such as screenshots of buttons or icons.
Use the following guidelines for including screenshots in online
Help:
-
Include a screenshot of the applet or application at the start
of the manual for the applet or application. The screenshot enables users to
verify that the manual describes the same applet or application that they are
viewing online.
-
Do not use screenshots indiscriminately in online Help.
-
Make sure that each additional screenshot is really necessary.
Bear in mind that the user usually has the application open in the GNOME
Desktop, so that a screenshot in the Help does not provide any additional
information.
Before you decide to use screenshots in online Help, consider the
following points:
-
Users must scroll screenshots to get to the next piece of
information. Screenshots slow down the user access to information.
-
Help that describes everything in text is more accessible to
users with disabilities than Help with text plus pictures. If a screenshot does
not provide additional technical information, then the Help is more complex
than necessary for disabled users.
-
Usability studies show that users can confuse Help screenshots
with the real application.
-
Task-oriented Help requires fewer screenshots than a
descriptive approach.
-
There is a requirement to update screenshots with product
development. If the screenshot and the product are out-of-step, you risk
confusing the user.
-
There is a requirement for accessibility text for every
screenshot. You must update this text each time the screenshot is updated.
There is a risk of the accessibility text being out-of-step with the
screenshot, or with the application. These factors add to the maintenance load
for the writer, and can confuse the disabled user.
-
Screenshots add to the localization burden and cost. The
localization team has to capture all screenshots in each language. Also,
translators have to translate the accessibility text associated with each
screenshot into each language.
Some GNOME Desktop distributions have a requirement to print manuals
covering broad topics, such as the
http://www.gnome.org/learn/users-guide/2.0/. The same
manuals are usually also a source of online Help, therefore you need to
consider the requirements for both online Help and for printed manuals. Many of
the issues associated with screenshots in online Help also apply to screenshots
in printed manuals. However, printed manuals are not always used in conjunction
with the application running on the GNOME Desktop. Therefore, you might need to
use more screenshots in printed manuals than in online Help.
Use the following guidelines for including screenshots in printed
manuals:
-
Do not use screenshots in printed manuals for aesthetic
purposes. For example, do not use screenshots for the sole purpose of breaking
up long passages.
-
Always ensure that there is a user requirement to see a
screenshot in a specific location.
-
Always ensure that the screenshots support the text, rather
than repeat what the text says.