
                       Using the Request System

This document is an explanation of various parts of the request system.
We will assume these things:
  - You've read the file called "intro" and have played with the request
    system a bit.
  - You have set up an alias called "systems" that the request system is
    being used to manage.
  - You have installed the programs with the default names that came
    with request, i.e. "q" and "req".

The system will work the same regardless of the names you actually used.

How to create a request
=======================
Any of:
  - send mail to systems 
    This has the side effect of sending mail to everyone.
  - run:
      req -create
    This has the side effect of not letting anyone know you created it.
  - run:
      req -mcreate - < mailfile
    This is very very useful for loading the system with all the old requests
    that had been mailed to you before you installed the request system.


How to look at a request
========================
Any of:
  - req -show #    
  - reqshow #  
  - cd /the/spool/directory/active ; cat #
  - use tkreq


Replying to requests when you have a stupid mailer
==================================================
Make sure you insert the [Req #foo] in your Subject: line.  Do it manually...
the request system won't notice the difference.


What if someone send mail with [Req #1500049] in the Subject?
=============================================================
The request system will create a request with that number, even if it
thinks it's only currently at #45.  You can do whatever you normally would
do.  The next request that comes in will get #46.

I would also suggest shooting the user, or explaining to them that if 
they'd like you to deal with their request, they should play by your rules.


What if someone replies but doesn't use the original request number?
====================================================================
Well, in that case, it will get a new number.  So, then you merge the two:
  req -merge new old

From that point on, both numbers will go to the same log.  You can do this
with any number of requests.... just keep merging them.


What if someone replies to me but not to systems?
=================================================
Oooooo, doncha just HATE that?  First of all, get it into the request system.
You can do this by forwarding the mail or by resending it.  Typically, if you
forward it, it'll get the headers munged and have a weirdly annotated body.
If you 'resend' it, it will appear as if it came from the original user.
This is a big win, but not all mail systems can do that.

Worst case, add it in by hand:
  req -comment # mailfile

Then, send mail to them, pointing out that all mail should go to systems.

Note that if you use 'tkreq' to send the mail, a "Reply-to: systems" will
automatically be added to the mail.  This is a big help, and you may want
to add it to your normal mailer as well.


How do I send mail to systems without it getting a request number?
==================================================================
You cc: it to systems instead of sending it directly.  If cc'd mail has
a number, then it gets appended to that number's log.  If it doesn't
already have a number, the mail is ignored.  This was designed 
intentionally so that people who cc announcements and such wouldn't 
generate bogus requests.  Occasionally it's a problem, and cc'd mail 
fails to get a request number when it should have.  In that case, you 
simply resend it to systems.

Note that as of 1.2, this is a configurable variable.  You can have
cc'd mail actually get a request number too.


What about discussion that happens between members of the list? 
===============================================================
Well, if it's about a request, it should probably get logged, so
using the list is fine.  If it's not (say, it's about meeting times),
we've found it enormously handy to have a different list for that sort
of thing.  That way, "systems" is all about things to do, whereas the
other is more of a discussion and coordination list.  This really
helps when you start using mail filters.


Why take requests?
==================
If you try to take a request (i.e. "req -take #") that is already owned
by someone, the request system will tell you that someone else owns it.
If you really want it anyway, steal it:  req -steal #

You can use the 'take' mechanism to make sure that only one person is working
on a request at a time by making this policy:
  Always 'take' a request before you do anything with it.

We don't actually follow that policy, but we come close.  Whether you do or
not is up to you.

If you see requests that you should be dealing with, do:
  req -take #


Why give requests?
==================
If you know someone else can answer the question or should answer the 
question.  If you're a boss, and want to assign someone to do something.
If you're an employee and you want your boss to do something.  If you've
worked on a problem for a while and it's now someone else's problem.

We always have one person (the hotseat) who's in charge of handling the
small problems that come in, and is supposed to give the big problems
to other people.

Because of this, 'giving' isn't a political move.  It may be in your
situation - that's up to you.

Mail is sent when someone is 'given' something, so that they're aware
that they're responsible for a request.  Likewise, they're told when the
request is taken from them.


Resolving requests
==================
Do:
  req -resolve #
Or:
  put in the mail header of a reply:
     X-Request-Do: resolve

"resolved" means that you think you're done with it.


Resolved things
===============
Resolved requests are kept in a different directory than active requests
for various reasons.  There are currently no decent tools to organize them 
better than that, but they're under construction


Ummm, I _know_ I resolved that.....
===================================
Sure you did.  But then someone did something to it.  Perhaps the user sent
more mail about it, or someone else a comment.  In any of those cases, it
wasn't really quite done with.  So the request was unresolved.  If you still
think it should be resolved, then re-resolve it.


Why let things be unresolved?
=============================
One way of handling resolving is to NEVER consider a request resolved until
the user agrees that it's been resolved.  That's how CERT works, as well as 
many of the major network providers.  You could do this with this system.

However, we get a LOT of requests, and we like to resolve things so that
they're out of our way.  Waiting for users to agree that little things are
resolved would generate at lot of email.  So we decided that we would make
the decision that something was resolved, and if the user disagreed, all
they would have to do is send more mail about it.  Then the system would
automatically unresolve it for us.  This seems to work pretty well.


What if a request is really bogus?
==================================
Like mail that should never have been sent to systems?  Kill it:
  req -kill #


How do _you_ use this whole thing?
==================================
We tend to use tkreq and q to look at the requests.  As someone working
on the queue, I look at my requests.  I look to see how old they are, and
what priority they are.  I use this information to make choices about what
to do next.  I may update priorities, or reply to users, letting them know
that I'm making progress.  I may even look at other people's requests if
I'm curious what's up.

As someone on the hotseat (i.e. dealing with new requests), I look at things
that aren't owned.  I handle them if I can, and send mail, resolving them if
at all possible.  If they're out of my scope, I give them to other people.
My goal is to make sure that someone owns all of the requests.  And I
run `reqtail -f' in a dedicated window, keeping an eye on all activity
in the req system.

As a manager, I look at how long it's been since people got feedback.  (This
is the "told" column.)  If it's been too long (a day or more), they may be
thinking we're a black hole, or that we're not working on a problem.  I also
look at priorities, and make things higher or lower priority.  If one person
has too many things to do, I may reassign requests to different people.


Any rules?
==========
Really only one:
  It doesn't exist unless it's in the request system.

By this, I mean simply that everything you need to do should be in the
request system.  Don't confuse yourself by having two or three different
lists of things to do, or it will make it harder to figure out what to do
next.

Initially, we only used the system to keep track of user requests.  We used
other things to keep track of internally generated things to do.  But it
turned out to be so useful to have the req tools to help prioritize that
we merged in our own requests as well.

Now, as soon as we think of something that needs to be done, we put it
in the request system.  That way, we don't have to try to remember to do it.


So now I have to watch TWO things: mail and the request queue.
=============================================================
To a certain extent, that's true.  However, you don't really have to
watch the mail anymore, and you don't have to keep it around forever
so that you remember to do things.  Mail becomes a way of keeping up
with changes, not a way of remembering things.

We're trying out various ways of keeping a chronology so that you don't
even have to get the mail anymore.


Now I get two copies of mail sent to me and systems.
====================================================
Yeah.  


What's next?
============
See the 'wish.list' file.

