documentation-guide/en_US writing-guidelines.xml,1.8,1.9
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Sun Jul 1 17:30:34 UTC 2007
Author: pfrields
Update of /cvs/docs/documentation-guide/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv6331
Modified Files:
writing-guidelines.xml
Log Message:
Clean up and improve screenshot guidelines
Index: writing-guidelines.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/writing-guidelines.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- writing-guidelines.xml 29 Jun 2007 00:10:59 -0000 1.8
+++ writing-guidelines.xml 1 Jul 2007 17:30:32 -0000 1.9
@@ -463,19 +463,22 @@
<see>screenshots</see>
</indexterm>
- <para>There are two types of screenshots: graphical and textual.
- The philosophy on using these two types is <firstterm>rely on text
- over graphics</firstterm>. This means, if you can say it in
- text instead of showing a graphic, do so. A graphical screenshot
- of a GUI can create a good setting of objects to then describe
- textually, but you don't want to create a screenshot for each
- graphical step.</para>
- <para>The main reason for this preference is that a block of text
- can usually convey more meaning than the same physical space of
- graphics. This is highly dependent on the graphic; obviously, a
- photographic image of a scene can convey more than 1000 words can.
- A GUI screenshot is usually full of blank space with a few
- elements that can just as easily be described or listed.</para>
+ <para>Screenshots are illustrations that show the state of a display
+ the user may encounter. Screenshots can be either graphical or
+ textual. However, screenshots use a great deal of space in a text
+ document to convey relatively small amounts of information. The
+ same space in the document can hold a greater amount of more
+ descriptive and helpful information. Therefore, authors should
+ avoid screenshots whenever possible in favor of descriptive
+ text.</para>
+ <para>One of the isolated instances in which screenshots are useful
+ is to demonstrate a physical screen layout that is unfamiliar to a
+ reader. <emphasis>This does not mean that illustrations of dialog
+ boxes are good uses of screenshots.</emphasis> On the contrary,
+ dialogs are simply instances of a user interface element with
+ which a reader is already familiar. An annotated diagram in
+ certain cases, however, explains to the reader where to find
+ functional landmarks on the screen such as menu bars.</para>
<para>The steps for taking a graphical screenshot illustrate how
using text to describe a procedure is more concise than a series
of screenshots.</para>
@@ -485,70 +488,62 @@
<listitem>
<procedure>
<step>
- <para>Set the theme to Bluecurve defaults. This gives a look
- that is familiar to most readers, and makes &FDP;
- documents consistent. From the panel menu, choose
- <guimenu>Preferences</guimenu>,
- <guimenuitem>Theme</guimenuitem> and select
- <guimenuitem>Bluecurve</guimenuitem> from the theme
- list.</para>
+ <para>Create a new user account to make screenshots. The
+ new account uses the distribution default theme, fonts,
+ and element sizes. The resulting screenshot has an
+ appearance familiar to the largest number of readers,
+ and makes &FDP; documents consistent.</para>
</step>
<step>
- <para>Set fonts to Bluecurve defaults as well. From the
- panel menu, choose <guimenu>Preferences</guimenu>,
- <guimenuitem>Fonts</guimenuitem>. Set the
- <guilabel>Application font</guilabel> and the
- <guilabel>Desktop font</guilabel> to Sans Regular 10.
- Set the <guilabel>Window Title font</guilabel> to Sans
- Bold 10. Set the <guilabel>Terminal font</guilabel> to
- Monospace Regular 10.</para>
- </step>
- <step>
- <para>Before taking the screenshot, try to resize the
- targeted GUI element(s) to the smallest possible size
- they can be. Your target is an image of 500 pixels or
- less. If you are doing a screenshot of more than one
- GUI element, you may need to resize the screenshot in a
+ <para>Before taking the screenshot, if possible, resize
+ the targeted GUI element(s) to the smallest possible
+ size. The target image should be 500 pixels wide or
+ less. If the screenshot includes more than one GUI
+ element, you may need to resize the screenshot in a
following step.</para>
</step>
<step>
<para>To take the screenshot, select the GUI element with
- your mouse, bringing it to the forefront, or otherwise
- arranging the elements. Press <keycombo>
+ the mouse to bring it to the forefront, or otherwise
+ arrange the elements. Press <keycombo>
<keycap>Alt</keycap>
- <keycap>Print Screen</keycap> </keycombo> to capture a
+ <keycap>Print Screen</keycap></keycombo> to capture a
single GUI window. For capturing the entire desktop use
- <keycap>Print Screen</keycap>. If you are taking a shot
- of multiple elements and have grouped them closely
- together, you can crop the resulting image in
- <application>The GIMP</application>. The image will be
- in the PNG format.</para>
+ <keycap>Print Screen</keycap>. If the shot includes
+ multiple elements grouped closely together, crop the
+ resulting PNG format image in <application>The
+ GIMP</application>.</para>
</step>
<step>
- <para>If you need to, you can resize using
- <application>The GIMP</application>. With the image
- open, right-click on it and choose
- <guimenu>Image</guimenu> -> <guimenuitem>Scale
- Image...</guimenuitem>. With the chain symbol intact,
- set the <guilabel>New Width</guilabel> to <guilabel>500
+ <para>If necessary, resize the image using
+ <application>The GIMP</application>. Open the image,
+ then right-click on it and choose
+ <menuchoice>
+ <guimenu>Image</guimenu>
+ <guimenuitem>Scale Image...</guimenuitem>
+ </menuchoice>. With the chain symbol intact, set the
+ <guilabel>New Width</guilabel> to <guilabel>500
px</guilabel>, and click <guibutton>OK</guibutton>.
- Be sure to <keycombo>
- <keycap>Ctrl</keycap> <keycap>s</keycap> </keycombo>
- to save your changes to your PNG before converting to
- EPS.</para>
+ Choose <menuchoice>
+ <guimenu>File</guimenu>
+ <guimenuitem>Save</guimenuitem>
+ </menuchoice> to save changes to the image before
+ converting it.</para>
</step>
<step>
<para>
With the image open in <application>The
- GIMP</application>, right-click on the image,
- selecting <guimenu>File</guimenu> ->
- <guimenuitem>Save As...</guimenuitem>. Under
- <guimenu>Determine File Type:</guimenu>, select
+ GIMP</application>, right-click the image, and select
+ <menuchoice>
+ <guimenu>File</guimenu>
+ <guimenuitem>Save As...</guimenuitem>
+ </menuchoice>. Under <guimenu>Determine File
+ Type:</guimenu>, select
<guimenuitem>PostScript</guimenuitem>, then click
<guibutton>OK</guibutton>. Allow flattening of the image
by clicking <guibutton>Export</guibutton>.</para>
- <para>In the <guilabel>Save as PostScript</guilabel>
- window, select <guilabel>Encapsulated
+ <para>A <guilabel>Save as PostScript</guilabel> window
+ appears. Select <guilabel>Encapsulated
PostScript</guilabel>, and click
<guibutton>OK</guibutton>.</para>
</step>
@@ -567,16 +562,16 @@
Follow these guidelines for textual screenshots:</para>
<itemizedlist>
<listitem>
- <para>If you use a graphical screenshot to illustrate a
- function, and the textual mode has identical functions,
- do not include both, unless omitting either would make
- your description unclear.</para>
+ <para>If a graphical screenshot illustrates a function,
+ and the textual mode has identical functions, do not
+ include both, unless omitting either would make your
+ description unclear.</para>
</listitem>
<listitem>
- <para>Make your information generic over specific, and
- omit any username and machine information if possible.
- Do not include the shell prompt unless it is vital to
- the demonstration.</para>
+ <para>Make the information generic over specific, and omit
+ any username and machine information if possible. Do not
+ include the shell prompt unless it is vital to the
+ demonstration.</para>
</listitem>
<listitem>
<para>Separate what the user types from sample command
More information about the Fedora-docs-commits
mailing list