'Autoduty' Achievo module usage instructions
============================================

1. What is it?
--------------
The 'autoduty' module is a planner for duties that people need to perform in a 
company. Mind you that this is not a professional planner for project tasks,
but a simple yet effective way to plan housekeeping-related tasks that need to
be done. We use it ourselves to plan daily grocery shoppings and weekly coffee
machine cleanings. 


2. Assumptions
--------------
1) You should have activated the autoduty module in Achievo. See the 
   doc/INSTALL file for instructions on how to install and activate the 
   module.
   
2) The user you are going to use to setup the autoduty module should have 
   access to all menuitems. Use the profile editor in the Employee menu to
   accomplish this.
   
3) Users in Achievo should have a contract. The contract (which can be added/
   edited when editing the employee record) defines on which days the user
   works and for how many hours a week. This information is used to determine
   the planning. 
   
   
3. Instructions
---------------
There are 2 menu items in the 'Duty planner' menu. One is for creating and 
configuring the jobs, the other one is for viewing or editing the current or
past planning.

3.1 Adding jobs.

  The first thing to do is to define a job. Enter a name for the job and
  select on which days the job needs to be performed. After you press 'save',
  you will be taken to a detail screen where the following things can be
  configured:
  
    - Description: This can be a multiline explanation of the job. It is
      printed on the planning, so you can use it to explain to the users
      what is to be done.
      
    - Days: the days on which the job should be performed. 
    
    - Re-assign frequency: if you select 'daily', then for each day on which
      the job needs to be done, a new person is selected. If you select 
      'weekly', the same person(s) will perform the job for the entire week.
      
    - People required: this is the minimum number of people required to
      perform the job. For example, if it takes at least 2 people to roll out
      the garbage container, you would select 2 here.
      
    - Optimal: this is the optimal number of people required to perform the
      job. If it takes 2 people to roll out the container, but it is more 
      convenient when 3 people do it, you would enter 3 here. The planning 
      script will try to honour the optimal number if possible, but if the
      desired number of people is not available, it will use at least the 
      minimum amount of people.
      
    - Schedule type: If you select 'structured', the module will keep exact
      track of how many times each user performed the job. It will use this
      to perform a 'fair' planning. Also, if people are parttimers, the module
      will take this into account when generating the planning. People working
      only half the time, will also have to perform the job only half as much
      as fulltimers. 
      If you select 'random' on the other hand, people are selected completely
      at random.
      
    - Participants: here you select the people that are supposed to do the
      job. You can use this to build a team of people that take turns in 
      performing the job. To easily add a number of people, you can add
      comma separated search terms in the box near 'Participant add', which
      allows you to quickly add a list of people based on some search string.
      If a job has been performed for a while, and you add a new participant, 
      his initial jobcount will be set to the minimum of the rest of the team,
      to prevent a situation where newcomers have to perform the job on their
      own for weeks.
      
3.2 Swapping jobs.

  Sometimes it will happen that person A was scheduled to perform a job, but 
  he swaps his duty with person B for whatever reason. If the planner script 
  is not notified of this change, it will unfairly schedule person B to do 
  the job next time.
  Using the menuitem 'job history' however, people can indicate the swap, and
  the planner will then take into account the change.
  
3.3 Generating the planning.

  The planning is automatically generated by a cron script, and mailed to the
  address configured in the script file (see doc/INSTALL, section 5). For
  testing purposes it is advisable to use your own address here, and when you
  are finished configuring the jobs, you can use a company mailinglist or a
  list of user addresses to mail to. (in a later version we will make this more
  flexible)
  
  If for some reason the planning does not look alright, just rerun it; the 
  script will remove already planned duties first and reschedule them nicely.