half-backed cleaning up of user guide

Author: Richard Jones

doc/user_guide.txt

@@ -2,16 +2,106 @@
 User Guide
 ==========
 
-:Version: $Revision: 1.7 $
+:Version: $Revision: 1.8 $
 
 .. contents::
 
 Note: this document will refer to *issues* as the primary store of information
 in the tracker. This is the default of the classic template, bubt may vary in
 any given installation.
 
+Your Tracker in a Nutshell
+==========================
+
+Your tracker holds information about issues in bundles we call *items*. An
+item may be an *issue* (a bug or feature request) or a *user*. The issue-ness or
+user-ness is called the item's *class*. So, for bug reports and features, the
+class is "issue", and for users the class is "user".
+
+Each item in the tracker has an id number that identifies it along with its
+item class. To identify a particular issue or user, we combine the class with
+the number to create a unique label, so that user 1 (who, incidentally, is
+*always* the "admin" user) is referred to as "user1".  Issue number 315 is
+referred to as "issue315". We call that label the item's *designator*.
+
+Accessing the Tracker
+---------------------
+
+You may access your tracker through one of three ways:
+
+1. through the `web interface`_,
+2. through the `e-mail gateway`_, or
+3. using the `command line tool`_.
+
+The last is usually only used by administrators. Most users will use the web
+and email interfaces. All three are explained below.
+
+
 Web Interface
--------------
+=============
+
+Note: this document contains screenshots of the default look and feel. Your
+site may have a slightly (or very) different look, but the functionality will
+be very similar, and the concepts still hold.
+
+The web interface is broken up into the following parts:
+
+1. `lists of items`_,
+2. `display, edit or entry of an item`_, and
+3. `searching page`_.
+
+
+Lists of Items
+--------------
+
+The first thing you'll see when you log into Roundup will be a list of open
+(ie. not resolved) issues. This list has been generated by a bunch of controls
+`under the covers`_ but for now, you can see something like:
+
+.. img: images/index_logged_out.png
+
+The screen is divided up into three sections:
+
+.. img: images/page_layout.png
+
+you may either register or log in. Registration takes you to:
+
+.. img: images/registration.png
+
+Once you're logged in, the screen changes slightly to:
+
+.. img: images/index_logged_in.png
+
+Note that the sidebar menu has changed slightly, so you can now get to your
+"My Details" page:
+
+.. img: images/my_details.png
+
+Note the new information on this page - the history.
+
+Create a new issue with "create new" under the issue subheading. This will
+take you to:
+
+.. img: images/new_issue.png
+
+Enter some information and click "submit new entry" and you'll be rewarded
+with:
+
+.. img: images/new_issue_created.png
+
+or, if you don't enter all the required information (or some other error
+occurs) you'll get something like:
+
+.. img: images/new_issue_error.png
+
+Searching
+---------
+
+TODO: some information about how searching works
+
+
+Under the covers
+----------------
 
 Index views may be modified by the following arguments:
 
@@ -30,24 +120,18 @@ propname   selects the values the item properties given by propname
            must have (very basic search/filter).
 ========== =============================================================
 
-Searching
-~~~~~~~~~
-
-TODO: some information about how searching works
-
-
 Access Controls
-~~~~~~~~~~~~~~~
+---------------
 
 
 Managing Issues
-~~~~~~~~~~~~~~~
+---------------
 
 TODO: some mention of how the various widgets work
 
 
 E-Mail Gateway
---------------
+==============
 
 E-mail sent to Roundup is examined for several pieces of information:
 
@@ -56,7 +140,7 @@ E-mail sent to Roundup is examined for several pieces of information:
 3. e-mail attachments which should be associated with the message
 
 Subject-line information
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 The subject line of the incoming message is examined to find one of:
 
@@ -84,7 +168,7 @@ item of the default class, and if there's a match, the message is related to
 that matched item. If not, then a new item of the default class is created.
 
 Setting Properties
-::::::::::::::::::
+~~~~~~~~~~~~~~~~~~
 
 The e-mail interface also provides a simple way to set properties on items. At
 the end of the subject line, propname=value pairs can be specified in square
@@ -113,7 +197,7 @@ off.
 
 
 E-Mail Message Content
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 Roundup only associates plain text (MIME type ``text/plain``) as messages for
 items. Any other parts of a message are associated as downloadable files. If
@@ -134,7 +218,7 @@ sections, then these will be stripped out of the message if the
 ``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``.
 
 Message summary
-:::::::::::::::
+~~~~~~~~~~~~~~~
 
 The "summary" property on message items is taken from the first non-quoting
 section in the message body. The message body is divided into sections by blank
@@ -144,7 +228,7 @@ non-quoting section becomes the summary of the message.
 
 
 Address handling
-~~~~~~~~~~~~~~~~
+----------------
 
 All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming
 message are
@@ -172,7 +256,7 @@ the message may be added to the `nosy list`_ depending on:
 
 
 Nosy List
-:::::::::
+~~~~~~~~~
 
 The nosy list watches for additions to the "messages" property of items.
 When a new message is added, it is sent to all the users
@@ -188,7 +272,7 @@ to determine if they get a nosy list copy of the message too.
 
 
 Command Line Tool
------------------
+=================
 
 The basic usage is::