Use guidelines while documenting installation and configuration tasks and other tasks that describe how to use features within a product.

Include screenshots when screenshots:

• Help reassure the user that where they are in the UI is the right place to be

• Help call attention to a specific area of a complex UI

• Support an example that is hard to visualize otherwise, for example, setting up a configuration that is not quite straight forward

Where they add value, documentation maintenance and localization might be time-consuming and costly. However, just as you would with words, omit the obvious and whatever does not add value.

Strive for an additive approach (add screenshots when the words seem inadequate) over a subtractive approach (do not include screenshots if they seem superfluous). In other words, be more open to screenshots in the future, but understand that they have to work in the document, not just be there because they can.

Considerations

Before you include screenshots in documentation, consider the following points:

• Task-oriented content requires fewer screenshots than a descriptive approach. Avaya DITA/XML information model dictates a task-oriented approach that reduces the need for screenshots.

• Usability studies show that users can confuse screenshots with the real application. Users must scroll screenshots to get to the next piece of information. Screenshots slow down the user access to information.

• Content that describes in detail in text is more accessible to users with disabilities than content with text plus pictures. If a screenshot does not provide additional technical information, then the content becomes complex for disabled users.

• Every screenshot requires accessibility text. 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. The alternate text must also be localized, which adds time and cost.

• Screenshots, in general, add to the translation 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.

• Assess the requirements for all publication methods and how the intended audience will use the content. Some Avaya products have a requirement to group documentation covering broad topics into “libraries” of information and PDF files which cover may areas of the product, such as administration and end user tasks. These deliverables bring together and reuse DITA/XML topics that may also appear as online help. PDF files are not always used in conjunction with the application.

Guidelines

Use the following guidelines for including screenshots in documentation:

• Do not use screenshots as a matter of course. Remember that the user usually has the application open, so that a screenshot does not provide any additional information and may cause confusion.

• Include a screenshot only when a procedure or step is complex and a screenshot will alleviate the need for numerous, convoluted steps. (In most cases, if a task is that complicated, you must suggest changes to the user interface which would make the task easier for the user.)

• Do not substitute screenshots for writing the text for the steps the user needs to perform and must only be used to provide clarification or validation. Do not use a screenshot to avoid including the appropriate text that tells the users what to do.

  Note:

  Where there are no screenshots, the procedure must clearly include the screens to select (show path) and the fields to click (or tab to) and mention the purpose of the screen, dialog box or field depending on where you are in the steps.

• Include a screenshot in the first concept topic of a component map to verify that the content describes the same interface that the user is viewing online (this is not mandatory if it is already clear). For example, use it to set context and to describe general navigation within an interface. The trade off is that when the user interface changes, you must recapture the screenshot and rewrite the text that increases the localization cost.

• Do not use screenshots for aesthetic purposes or because it looks better to start all procedures with screenshots. For example, do not use screenshots to break up long passages, or to show that every step in a task has been completed correctly.

• Ensure that a screenshot supports the text, rather than verifies or repeats what the text says.

• You do not get the higher resolution or ability to translate text in SVG graphics. But if you plan to include any text callouts with your screen capture, use SVG because the text callouts can be translated.

  To avoid text callouts, you can use PNG image, add numbers to identify specific portions in the image, and add the text description in a simple table that follows the image.

Tool recommendations

You may use

• Snipping Tool to capture screenshot.

• Gimp or Inkscape to create and edit images and add text.