gnome-devel-docs 3.8.1-1 / usr / share / help / sl / hig-book / hig-ch-language.xml

<?xml version="1.0" encoding="utf-8"?>
<chapter id="language" lang="sl">
    <title>Language</title>

    <para>Consistent labelling creates a familiar environment that the user can navigate comfortably. The more familiar the environment, the easier task of finding information.</para>

    <sect1 id="language-labels">
      <title>Labels</title>
      
      <sect2 id="language-controls"> 
	<title>Controls</title> 
	<para>Clear, consistent and concise labelling of controls helps users to work out the purpose of a window or dialog they have never seen before. To a visually-impaired user, clear labels are even more important. A user who relies on a screenreader has no assistance from icons, layout, or spacing to work out what the controls do, so clear labelling is essential.</para>
	
	<itemizedlist><title>Guidelines</title> 
	  <listitem><para>Keep labels short.  This:
	    <itemizedlist> 
		<listitem><para>Reduces the expansion of text when translated, and thus minimizes the effort required to localize the UI. Translated English text can expand up to 30% in some languages.</para></listitem> 
		
		<listitem><para>Facilitates the use of translation engines.</para></listitem> 
		<listitem><para>Improves speed of comprehension for the user.</para></listitem> 
	      </itemizedlist> 
         </para>
	    
	    <para>Do not shorten your labels to the point of losing meaning, however. A three-word label that provides clear information is better than a one-word label that is ambiguous or vague. Try to find the fewest possible words to satisfactorily convey the meaning of your label.</para></listitem> 
	  
	  <listitem><para>Do not include text in windows that describes <emphasis>how</emphasis> to use the interface, for example <guilabel>You can install a new theme by dropping it here</guilabel>.  As well as adding visual clutter, descriptive labels can also conflict with information provided in documentation.</para></listitem> 
	  
	  <listitem><para>Use standard terms.  You can find a list of standard user interface terms in the <ulink url="http://developer.gnome.org/gdp-style-guide/stable/wordlist.html.en">GNOME Documentation Style Guide, Recommended Terminology</ulink>.</para></listitem> 
	  
	  <listitem><para>Apply standard capitalization rules.  See <xref linkend="layout-capitalization"/> for guidelines about capitalization of user interface labels </para></listitem> 
	</itemizedlist>

      </sect2> 
      
      <sect2> 
	<title>Tooltips</title> 
	
	<sect3>
	  <title>Toolbar Tooltips</title>
	  
	  <para>A toolbar tooltip is the short description of a toolbar control's functionality that the user sees when they mouse over it.</para>

	  <itemizedlist> <title>Guidelines</title>
	    <listitem><para>Concisely state the purpose of the control.  The tooltip should be more descriptive than the corresponding menu item name, if there is one, but not verbose.  For example, <guilabel>Undo last action</guilabel> for the <guibutton>Undo</guibutton> button.</para></listitem> 

	    <listitem><para>Use sentence capitalization rules. See <xref linkend="layout-capitalization"/>.</para></listitem> 
	  </itemizedlist>            
	  
	</sect3> 
	
	<sect3>
	  <title>Application Tooltips</title> 

	  <para>An application tooltip is the short description of your application that the user sees when they mouse over the launcher or menu item for your application.  It is stored in the <structfield>comment</structfield> field of your application's <filename>desktop</filename> file. See <xref linkend="menu-item-tooltips"/></para>

	  <itemizedlist><title>Guidelines</title> 
	    <listitem><para>Create short tooltips. Aim to accurately communicate the functionality of an element with the fewest words possible.</para></listitem> 
	    <listitem><para>Use sentence capitalization rules. See <xref linkend="layout-capitalization"/>.</para></listitem> 
	    
	    <listitem><para>Use standard punctuation rules, with the exception that you do not use a period to end the tooltip.</para></listitem> 
	    
	  </itemizedlist> 
	</sect3> 
      </sect2> 
      
      
      <sect2> 
	<title>Menus</title> 
	
	<itemizedlist> <title>Guidelines</title>
	
	  <listitem><para>Use the recommended standard labels for menu items and titles, where they exist. Do not use synonyms such as <guimenuitem>Exit</guimenuitem> instead of <guimenuitem>Quit</guimenuitem>. See <xref linkend="menus-standard"/> for a list and descriptions of standard menu items and titles.</para></listitem>

	  <listitem><para>Use header capitalization rules for all menu items and titles. See <xref linkend="layout-capitalization"/> for more information.</para></listitem> 
	    
	</itemizedlist> 
	
      </sect2>
      
    </sect1>

    <sect1 id="language-errors">
      <title>Warning and Error Messages</title>
	<para>A good warning or error message contains two elements:</para>
	<orderedlist>
		<listitem><para>A brief description of the problem.</para></listitem>
		<listitem><para>A list of ways the user can remedy the problem.</para></listitem>
	</orderedlist>

	<para>Both of these elements should be presented in non-technical, jargon-free language, unless your target audience is particularly technically-minded.</para>

	<para>If your application knows enough about the problem to be able to give all this information to the user, it will often be capable of rectifying the problem itself when the user has decided which course of action they want to take.  For example, if the problem is insufficient memory, tell the user which currently-running application is taking up the most memory, and provide a button to close it for them.  (Do not offer to launch a graphical process manager, however, which is something most users should never see!)</para>

	<para>See <xref linkend="windows-alert"/> for more detailed information on writing and presenting errors, warnings and information alerts.</para>
    </sect1>


    <sect1 id="language-help">
      <title>Online Help</title>
	<para>Writing online help is a specialized task, and is therefore not covered in any depth here.  Refer to the <ulink url="http://developer.gnome.org/gdp-style-guide/stable/">GNOME Documentation Styleguide</ulink> for guidance on writing clear, consistent and helpful documentation for your application.</para>
    </sect1>

  </chapter>