<chapter id="usage_guide"><title>Usage Guide</title>

<sect1 id="tracking_the_project"><title>Tracking the Project</title>

<para>Once the initial plan has been made and the project has started,
TaskJuggler can be turned from a planning tool into a tracking tool.
You don't have to change a lot to do this. After all, as the initial
plan is almost always just a first guess, you need to continue
planning your project as new details become evident. So what you
really want is a way to gradually freeze the plan as work has been
completed, while still having full flexibility with all future
work.</para>

<para>While it is generally accepted to invest some amount of time
in project planning, it is very common that once the project has
been started, project managers tend to avoid a proper tracking of the
project. Our bet is that the vast majority of project plans are only
made to get management or investor approval. After the approval phase,
many project managers only work with their project plan again when the
project is running really late. On the other hand there are projects
that are done using strict project management techniques that
require detailed status tracking. Both extremes probably have their
fans and TaskJuggler offers good support for both extremes as well as
various techniques in between.</para>

<sect2 id="recording_progress"><title>Recording Progress</title>

<para>As mentioned previously, your initial project plan is only a
first estimate of how the project will progress. During the course of
the project you will have to make changes to the plan as new
information needs to be taken into account and you probably want to
track the progress of the project in a formalized form. TaskJuggler
will support you during this phase of the project as well, but it
needs your help. You have to provide the additional information in the
project file. In return you get current status reports and an updated
project plan based on the current status of the project.</para>

<para>The most simple form of capturing the current status of the project
is to use the <link linkend="PROPERTY_complete">complete</link>
attribute.</para>

<para><screen>
task impl "Implementation" {
  depends !spec
  effort 4w
  allocate dev1, dev2
  complete 50
}
</screen></para>

<para>This tells TaskJuggler that 50% of the task's effort has been
completed by the current date. Tasks that have no completion
specification will be assumed to be on track. TaskJuggler calculates
the completion degree based on the current date. Completion
specifications only need to be supplied for tasks that are either
ahead of schedule or behind schedule. Please keep in mind that the
completion degree does not affect the scheduling and resource
allocation. It is only for reporting purposes. It also does not tell
TaskJuggler which resource actually worked on the tasks.</para>

<para>If you want the past work to affect scheduling you must use
the booking statements as outlined in the next section.</para>

<para>When your project plan reflects the current status of your
project, TaskJuggler can generate nice status reports for you. To
generate an HTML report for the last week listing all tasks that are
running late, all tasks that are ongoing, tasks that have been
completed last week, and task that will be started next week, you
just specify <screen>
htmlstatusreport "Status-Report.html" {
}
</screen></para>

</sect2>
<sect2 id="recording_resource_usage"><title>Recording Resource Usage</title>

<para>The initial project plan should be made by entering the minimum
amount of required information such as task dependencies and efforts.
TaskJuggler will then compute all the missing data based on this initial setup.
This is your project baseline. As the project progresses you can now track
the work already completed by recording the work that your resources
have done. Let's assume you had the following task in your original plan:
<screen>
task impl "Implementation" {
  depends !spec
  effort 4w
  allocate dev1, dev2
}
</screen></para>

<para>After the first week of work on this task the two resources have
really been able to complete half the job. You can capture this in
your project plan using the <link
linkend="PROPERTY_booking">booking</link> attribute. Bookings are
resource specific, so you have to add the booking to the resource
definition, not the task definition.</para>

<para><screen>
resource dev1 "Developer 1" {
  booking impl 2005-04-11 - 2005-04-16 { sloppy 2 }
}

resource dev2 "Developer 2" {
  booking impl 2005-04-11 - 2005-04-16 { sloppy 2 }
}
</screen></para>

<para>The sloppy attribute defines the accuracy of your bookings. If
it's missing or 0, the booking must only describe a continuous working
period during working hours. With higher values the interval may
overlap with off-hour or vacation time slots. See <link
linkend="PROPERTY_sloppy">details on sloppy</link>.</para>

<para>If you don't like to mix the resource definitions and their
bookings, you can specify the bookings with <link
linkend="PROPERTY_supplement">supplement</link> statements.
These supplement statements can even reside in an other file. Some
companies have created a web front-end for their developers to report
the completed work against the project plan. The reports are stored in
a database and include files for TaskJuggler are generated from this
database. This way the project manager gets a very current status of
the project and can compute the current project plan based on these
data without much effort. If you are interested in this you should
have a look at the download section of the <ulink
url="http://www.taskjuggler.org">TaskJuggler web site</ulink>.</para>

<para>It is ok to specify bookings beyond the effort value found in
the task definition. In case you want to declare a task as done, even
if the bookings do not reach the specified effort or length, you can
use the <link linkend="PROPERTY_scheduled">scheduled</link>
property.</para>

<para><screen>
supplement task impl {
  actual:scheduled
}
</screen></para>

<para>As a side note we would like to mention that the recording of
the work time of employees is regulated by labor law in certain
countries. You might also require approval from a Worker's Council before
you can deploy time recording tools.</para>

<para>In case your actual progress does not deviate a lot from your
project plan, you can generate the file with the booking statements
automatically.</para>

<para><screen>
export "DoneWork-Week15.tji" {
  hideresource 0
  start 2005-04-11
  end 2005-04-16
  properties bookings
}
</screen></para>

<para>This will generate a TaskJuggler include file that contains all
bookings according to the project plan for the specified interval. You
can then use this file as a baseline and modify it to reflect the real
work that has happened during the interval. After that you can include
it into your project again.</para>

<para><screen>
include "DoneWork-Week15.tji"
</screen></para>

<para>As this include file references the tasks and resources of your
project you should include it after all task and resource
definitions.</para>

<para>To make TaskJuggler aware that you want to compute the end date
based on the bookings and the effort you need to enable the
<link linkend="PROPERTY_projection">projection</link> mode for the scenario.
This has to be done in the scenario definition in the project
header. If you don't have a scenario definition because you are only
using the built-in default scenario, you have to add a scenario
definition.</para>

<para><screen>
project prj "Project" "1.0" 2005-04-01 - 2005-05-01 {
  scenario plan "Plan" {
    # Compute when the task will be ready based on the already
    # done work and the current date.
    projection
  }
}
</screen></para>

<para>TaskJuggler now assumes that for all tasks that have bookings, all
work has been specified with bookings up to the current date. It then
calculates the end date of the task based on the effort that is still
left over. It also computes the <link
linkend="PROPERTY_complete">complete</link> value based on the
specified bookings. So if you specify bookings for a task you should
not specify a completion value as well. It will be ignored and
replaced by a value based on the specified bookings.</para>

<para>When you now schedule the project again, it will take these bookings
into account and generate a new project plan based on your current
project status.</para>

<para>Each time you review your project status you should generate
such an include file for the period that you are reviewing. Then you
sync the content with the feedback that you get from your resources and
add the file to the project plan.</para>

</sect2>
</sect1>
<sect1 id="freezing_your_project"><title>Freezing your project as it progresses</title>

<para>During the planning phase of the project you want to specify as
little as necessary and have TaskJuggler calculate the rest of the
project variables. As the project progresses, more and more variables
turn into constants. Whenever this happens, you should tell
TaskJuggler about it. If you don't do this, TaskJuggler will assume that
it has full freedom to pick these values and you will end up with a
project plan that has nothing to do with the past part of the project.
Especially when you have a fairly dense resource allocation, the plan
will become very dynamic. Small changes in the plan can result in a
significantly different scheduling result. The scheduling algorithm
that is used by TaskJuggler is fairly complex and always tries to
achieve the best possible result. It does not know that you have
scheduled the project before and expect a similar result after the
changes. The result is always correct according to the specification
you have entered, but it can differ a lot even after fairly small
changes. That is why you have to tell TaskJuggler when scheduled
values have become reality and are no longer flexible.</para>

<para>Once a task has been completed it is a good idea to
remove the allocation statements from this task to prevent accidental
resource allocations when the bookings don't exactly sum-up to the
required effort. If you have specified all work on a task by bookings,
you could also remove any hardcoded start and end dates as well as
dependencies, but this is not required. You just have
overspecified the task. In case you have made contradicting
statements, TaskJuggler will issue an error message. This is for
example the case when you have a fixed start date and a booking that
starts earlier than this start date.</para>

<para>In general it is perfectly ok to overspecify your project. For
example, you can have a fixed start date on a task as well as a start
dependency. As long as they don't contradict each other, they can
peacefully live together and you can use them as additional check
points.</para>

<para>The following example contains the minimal elements to freeze
your project as it progresses.</para>

<para><screen>
&Freeze_Example;
</screen></para>

<para>The <computeroutput>now</computeroutput> property is only used to
illustrate that we want to freeze the project one week after it
got started. The scenario definition is necessary to switch the
scheduler into projection mode. It will then assume that all resource
allocations prior to the current date have been specified. It will
only allocate resources after that date on its own. The export report
outputs all allocations for the time prior to the current date. These
are either the allocations generated by the scheduler or the ones that
are provided in the included file. But keep in mind that the
scheduler only generates allocations after the current date. So, when
you start the project with an empty include file, you need to set the
<computeroutput>now</computeroutput> date to the start of the project.
Even though the include file gets rewritten every time you regenerate
the reports, changes you have made in this file will not get lost.
TaskJuggler will always include the current version prior to rewriting
the file with potentially extended information. Therefore it is
possible to start with a generated version of the allocations and then
modify them to reflect what really happened.</para>

</sect1>
</chapter>