Hi all, As a part of the OPW internship, I have taken up the task of updating gedit help pages. I came across an instance of usage of stock icon being used inline (that is, within paragraphs) along with help content as part of the instructions to users.[1]
While it's very helpful to include screenshots of UI to help user locate the right icon, particularly those that by default have no text or a button that sets it's label from some user selectable value, this practise breaks the line spacing in the paragraph and thus affects readability. UI icon screenshots are not particularly user or accessibility friendly and most importantly not theme agnostic. Hence defeating one of the goals of GNOME Documentation team: GNOME help must be written to be consistent across GNOME programs. Solution 1: Mallard supports style tags for menu and menuitems which can be used to mark up <gui> tags instead of the instructions to press toolbar icons. Solution 2: If however, the screenshot cannot be done without, we can use: <figure> <title>Mallard Logo</title> <desc>a question-mark-shaped duck head in a circle.</desc> <media type="image" src="mallard-logo.png"/> </figure> This example uses the image as the focus and description tag could be used to place help instructions associated with the image. Though, this puts too much emphasis on the screenshot and thus requiring the screenshot to be a full window for aesthetics sake than a little piece of it. Could you suggest something more subtle and effective? :) Thank you. -Sindhu [1] https://git.gnome.org/browse/gedit/tree/help/C/gedit-view-open-files-in-sidepane.page _______________________________________________ gnome-doc-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/gnome-doc-list
