Clean up and improve screenshot guidelines

1 files changed, 63 insertions, 68 deletions

diff --git a/en_US/writing-guidelines.xml b/en_US/writing-guidelines.xml
index 0691825..0eaf2e7 100644
--- a/en_US/writing-guidelines.xml
+++ b/en_US/writing-guidelines.xml
@@ -51,7 +51,7 @@
       <para>Any time the file is committed to CVS, the line is updated
 	automatically to include information about the file. For
 	example:</para>
-      <screen><![CDATA[<!-- $Id: writing-guidelines.xml,v 1.8 2007/06/29 00:10:59 pfrields Exp $ -->]]></screen>
+      <screen><![CDATA[<!-- $Id: writing-guidelines.xml,v 1.9 2007/07/01 17:30:32 pfrields Exp $ -->]]></screen>
     </section>
   </section>
   <section id="sn-id-naming-conventions">
@@ -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> -&gt; <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> -&gt;
-		<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