<?xml version="1.0"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

<!-- ################# Writing Application Manuals ###############-->
  
  <sect1 id="writingapplicationmanuals">
    <title>Writing Application and Applet Manuals</title>
    <para>
	  Every GNOME application or applet should have a manual specific
      to that particular application. This manual should be a complete
      and authoritative guide.  The manual should describe what the
      program does and how to use it.  Manuals will typically describe
      each feature and preference option presented to the user using 
	  screenshots (in PNG format only) when appropriate.  They should also 
	  describe each window and panel if available.
    </para>
	<para>
	  An invaluable resource to the documentation writer is the GNOME 
	  Documentation Style Guide (GDSG or just style guide).  The style guide 
	  gives pointer to writing documentation, word usage, usability, and 
	  DocBook style.  There are check lists for writing good documentation.  
	  The style guide contains guidelines for writing to an international 
	  audience so translations of the documentation don't lose content in 
	  translation.  An approved word list and definitions are available so 
	  a set of basic technical words have the same meaning.  It is always 
	  handy to keep the style guide at your side or in a hardcopy so you 
	  can refer to it while writing documentation.  The GNOME Documentation 
	  Style Guide can be obtained at <ulink url="http://library.gnome.org/devel/gdp-style-guide/stable/">
		http://library.gnome.org/devel/gdp-style-guide/stable/</ulink> or 
	  in the SVN module <filename class="directory">gnome-devel-docs/trunk/gdp-style-guide</filename>.
	</para>
    <note>
      <title>Documentation Availability</title>
      <para>
        Applications and applets should not rely on documentation
        which is only available on the internet.  All manuals and
        other documentation should be packaged with the application or
        applet and be made available to the user through the standard
        GNOME help system methods described below.
      </para>
    </note>
    <para> Application manuals should be based on the template in
    for GNOME version 2.x..  Applet manuals should be based on
    the templates for GNOME versions 2.x.
    </para>
    <note>
      <title>Manuals For Large Applications</title>
      <para>
        Manuals for very large applications, such as GNOME Office
        components should be a <sgmltag>&lt;book&gt;</sgmltag> (and thus
        use <sgmltag>&lt;chapter&gt;</sgmltag> for each primary section)
        , instead of <sgmltag>&lt;article&gt;</sgmltag> which most
        applications use (with each primary section being a
        <sgmltag>&lt;sect1&gt;</sgmltag>).
      </para>
    </note>
<!-- This is not quite right.
    <note>
      <title>Applet Manuals in GNOME 2.0</title>
      <para>
        Note that applet manuals in GNOME 2.0 are treated in a special
        way.  The manuals for all applets are merged into a single
        virtual document by Nautilus.  For this reason, the header
        information for applet manuals is omitted and the  first
        section of each applet is
        <sgmltag>&lt;sect1></sgmltag>. Applet manuals will typically
        have several sections, each of which is
        <sgmltag>&lt;sect2></sgmltag>.
      </para>
    </note>
-->
    <para>
      Application manuals should be made available by having a
      <guimenuitem>Contents</guimenuitem> entry in the 
      <guimenu>Help</guimenu> pull-down menu at the top of the 
      application, as described in <xref linkend="listingdocsinhelpmenu" />.
      Applets should make their manuals available by
      right-clicking on the applet. 
    </para>
  </sect1>
