Keycloak

1
[[screenshot_guidelines]]
2
= Documentation Screenshots Guidelines
3

4
[[summary]]
5
== Summary
6
* Images should be saved as *PNG* or *JPG*, with a width of at least *660 px*, at *110 dpi*. Try to keep file size less than *300 KB*.
7
* Screenshots supplement the text, not replace it.  *Do not rely on images to provide information or context*.
8
* *Do not include any testing/pre-release labels*.
9
* *Do not include any personally identifying information*.
10
* Capture just the part of the screen or window that users must focus on; *do not include window headers in the final screenshots unless completely necessary*.
11
* Manipulate your screenshots to *condense important information* in them and limit empty GUI space and other inconsequential parts.
12

13
[[general]]
14
== General Guidelines
15
* Screen captures can be useful and successful when they achieve one or more of these objectives:
16
** Illustrate a user interface that is fairly complex or difficult to explain in text
17
** Help the user find a small element in a complex user interface
18
** Show the results of a series of steps or user actions
19
** Orient readers who are reading the publication without the user interface in front of them
20
* Use the smallest number of screenshots possible.
21
* Use screenshots to provide verification for the reader, rather than instruction. In other words, screenshots supplement the text, not replace it.  *Do not rely on images to provide information or context*. Instead, use them only to provide the reader with orientation.
22

23
[NOTE]
24
=====================================================================
25
Example 1:  Do not tell the reader to fill out a form according to the image; instead list the values needed for the form in text.
26
=====================================================================
27

28
[NOTE]
29
=====================================================================
30
Example 2: Do not include an image of the directory tree; instead tell the user exactly where to find the file in running text (…​/standalone/configuration/standalone.xml).
31
=====================================================================
32
* Bearing in mind the impact on localization and accessibility, you should aim to write your document so that, were you to remove all screenshots from the book, the text would still make sense.
33

34
[NOTE]
35
=====================================================================
36
For example: Do not write "see image below" or "as is shown in the image"
37
=====================================================================
38
* When you are snapping a GUI form, fill it with relevant input first.
39
* Make sure the screenshots *do not include any testing/pre-release labels*.
40
* Make sure the screenshots *do not include any personally identifying information*.
41

42
[NOTE]
43
=====================================================================
44
For example: Always use 'test' as the username or fake contact information. If including the browser title bar hide your bookmarks and use a default browser theme.
45
=====================================================================
46

47
[TIP]
48
=====================================================================
49
Use Chrome Dev Tools to select elements on the page and rewrite their contents.
50
=====================================================================
51
* Include the cursor, mouse pointer, or menus only when their presence is significant.
52
* Increase font size in the browser if it is hard to read before snapping the image.
53
* Capture just the part of the screen or window that users must focus on.
54

55
[NOTE]
56
=====================================================================
57
For example: Unless necessary, *do not include window headers in the final screenshots* to indicate your currently used window manager or desktop environment.
58
=====================================================================
59
* If possible, try not to cut any elements on the screen.
60
* Show the user interface elements exactly as they are displayed for most users for quick recognition.
61

62
[NOTE]
63
=====================================================================
64
For example: If you have a custom theme on your system, disable it and take the screenshot using the default theme.
65
=====================================================================
66
* Do not add borders around or drop shadows to your screenshots.
67
* Do not use rounded corners. If the screenshot contains rounded corners, then that's ok, of course. But, the screenshot itself should remain squared.
68

69
[[specs]]
70
== Tech Specs
71
* Image width should be at least *660 px* (internal tools will automatically resize the image to a max width of 660 px).
72
* The preferred format is *PNG* or *JPG* .
73
* The output resolution of images should be *110 dpi* to ensure good quality in the generated PDF.
74

75
[TIP]
76
=====================================================================
77
In GIMP, select Image/Scale Image... to set resolution
78
=====================================================================
79
* If possible, try to keep screenshot size less than *300 KB*.
80
* If possible, avoid snapping images in various terminals with 8-bit color scale or less.
81
* Manipulate your screenshots to condense important information in them and limit empty GUI space and other inconsequential parts.
82

83
[NOTE]
84
=====================================================================
85
For example: You can do this by setting a low screen resolution or resizing your browser window to a smaller size. Keep in mind that you should only do this if it does not adversely affect the readability of the image.
86
=====================================================================
87

88
[NOTE]
89
=====================================================================
90
If you need to take a screenshot of the entire window, use a tool such as the https://chrome.google.com/webstore/detail/window-resizer/kkelicaakdanhinjdeammmilcgefonfh?hl=en[_Window Resizer_] Google Chrome extension to ensure the browser window is a set size before taking the screenshot. This helps ensure that all full window screenshots are of standard dimensions.
91
=====================================================================
92
* If necessary, call attention to hard to find parts of the screenshot with red outlines (border: #C00, width:1px) or with a transparent gray (#ECECEC) layer over unimportant parts of the picture.
93

94
[[accessibility]]
95
== Accessibility
96
* Section 508 compliance requires that all of the information is available in a text format for accessibility reasons (for instance, screen readers can not extract information from images).
97
* Also, a large number of screenshots can possibly slow download of docs for those on very slow connections (rarer for most enterprises these days).
98

99
[[asciidoc]]
100
== AsciiDoc Syntax
101
* Insert a block-level image, which uses a double colon (::). Good for screenshots, diagrams, etc.
102

103
** Example 1: Include an image title in title case (which automatically appends a Figure #).
104
+
105
----
106
.Image Title
107
image::icon.png[Alt text, 50, 50]
108
----
109

110
** Example 2: Insert an inline image. Note, there is only one colon (:) used here.
111
+
112
----
113
This is an inline image. image:icon.png[Alt text] Cool!
114
----
115

116
[[questions]]
117
== Additional Questions
118
* When should I add a screenshot to my book?
119
** When  introducing a new part of the UI.
120
** When the UI is suboptimal and some elements are difficult to find, located in unusual places, hidden, or somehow less visible.
121
* When, in the development cycle, should I add my screenshots?
122
** Add them as late in the cycle as possible, preferably during the review process. At this late stage, hopefully there will be fewer UI changes to the product.
123

124
[TIP]
125
=====================================================================
126
Add a placeholder for the screenshot early on in the development cycle. This way it will not be forgotten.
127
=====================================================================
128
* What image editor should I use?
129
** The recommended graphical editor is GIMP.
130

131
[[extensions]]
132
== Browser Extensions
133

134
[[resizing]]
135
=== Resizing
136
There are a couple simple browser extensions that can assist in resizing your browser to the appropriate dimensions.
137

138
* Google Chrome extension: https://chrome.google.com/webstore/detail/window-resizer/kkelicaakdanhinjdeammmilcgefonfh?hl=en[_Window Resizer_]
139
* Firefox add-on: https://addons.mozilla.org/en-US/firefox/addon/firesizer/[_Firesizer_]
140
** You will also need to install the Addon Bar: https://addons.mozilla.org/en-US/firefox/addon/the-addon-bar/[_The Addon Bar (Restored)_]
141