e9a04593dff7773be9a094eaccfb51e21f538ae0
[worg.git] / org-tutorials / org-taskjuggler.org
1 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
2 #+STARTUP:    align fold nodlcheck oddeven lognotestate
3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
5 #+TITLE:      Creating Gantt charts by Exporting to TaskJuggler
6 #+AUTHOR:     Christian Egli
7 #+EMAIL:      christian DOT egli AT sbs DOT ch
8 #+LANGUAGE:   en
9 #+PRIORITIES: A C B
10 #+CATEGORY:   worg
11
12 [[file:index.org][{Back to Worg's index}]]
13
14
15 * Introduction
16 [[http://orgmode.org/][Org mode]] is an excellent tool for project planning as Peter Jones has
17 shown in his article on [[http://www.contextualdevelopment.com/articles/2008/project-planning][project planning]]. He first breaks the project
18 into features and tasks, then estimates the effort and from that
19 presents a project plan. In this tutorial we will take this one step
20 further, assign resources to the tasks, schedule the tasks and create
21 the corresponding gantt chart for this project.
22
23 We will be using [[http://www.taskjuggler.org/][TaskJuggler]] to handle the task scheduling, resource
24 leveling and creation of a myriad of charts (such as [[http://en.wikipedia.org/wiki/Gantt_chart][Gantt chart]]) for
25 your customer or your [[http://en.wikipedia.org/wiki/Pointy-haired_Boss][Pointy-haired Boss]].
26
27 * Plan your project
28 You start out as you normally would by breaking down the project into
29 tasks. Let's take the following example where you have a project to
30 create an accounting software:
31
32 #+BEGIN_SRC org
33 ,* Accounting Software
34
35 ,** Specification
36
37 ,** Software Development
38 ,*** Database coupling
39 ,*** Back-End Functions
40 ,*** Graphical User Interface
41
42 ,** Software testing
43 ,*** Alpha Test
44 ,*** Beta Test
45
46 ,** Manual
47
48 ,** Milestones
49 ,*** Project start
50 ,*** Technology Preview
51 ,*** Beta version
52 ,*** Ship Product to Customer
53 #+END_SRC
54
55 * Estimate the effort
56 Now that you've figured out the tasks it's time to estimate the
57 efforts for each task. By using column view this can be done very
58 efficiently. It also helps to define the =COLUMNS= and default values
59 for the Effort property as shown in the following screen shot:
60
61 #+CAPTION: Estimating effort using column view 
62 #+ATTR_HTML: alt="Estimating effort using column view"
63 [[file:../images/taskjuggler/effort-estimation.png]]
64
65 Your resulting Org mode project file will look somewhat like the
66 following:
67
68 #+BEGIN_SRC org
69 ,#+PROPERTY: Effort_ALL 2d 5d 10d 20d 30d 35d 50d 
70 ,#+COLUMNS: %70ITEM(Task) %Effort
71
72 ,* Accounting Software
73
74 ,** Specification
75    :PROPERTIES:
76    :Effort:   20d
77    :END:
78
79 ,** Software Development
80
81 ,*** Database coupling
82     :PROPERTIES:
83     :Effort:   20d
84     :END:
85
86 ,*** Back-End Functions
87     :PROPERTIES:
88     :Effort:   30d
89     :END:
90
91 ,*** Graphical User Interface
92     :PROPERTIES:
93     :Effort:   35d
94     :END:
95
96 ,** Software testing
97 ,*** Alpha Test
98     :PROPERTIES:
99     :Effort:   5d
100     :END:
101
102 ,*** Beta Test
103     :PROPERTIES:
104     :Effort:   20d
105     :END:
106
107 ,** Manual
108    :PROPERTIES:
109    :Effort:   50d
110    :END:
111
112 ,** Milestones
113 ,*** Project start
114 ,*** Technology Preview
115 ,*** Beta version
116 ,*** Ship Product to Customer
117 #+END_SRC
118
119 * Generate a Gantt chart
120 Before you now export the project to TaskJuggler you need to tell the
121 exporter in which tree it can find the tasks. You do this by adding
122 the tag ~taskjuggler_project~ to the node "Accounting Software"[fn:1].
123 Do this by moving to the "Accounting Software" headline and typing the
124 following:
125
126 : C-c C-c taskjuggler_project RET
127
128 This allows you to have other nodes for this project such as an
129 introduction or general notes.
130
131 To export the project to TaskJuggler you simply type 
132
133 : M-x org-export-as-taskjuggler-and-open
134
135 This will open your project in TaskJugglerUI as illustrated below
136
137 #+CAPTION: Gantt chart in TaskJugglerUI
138 #+ATTR_HTML: alt="Gantt chart in TaskJugglerUI"
139 [[file:../images/taskjuggler/TaskJugglerUI1.png]]
140
141 Since we have not assigned any resources to work on the project the
142 exporter assumes that you will be the one working on it and has
143 assigned all tasks to you. The tasks have been serialized so that you
144 will not have to many things to do at once, i.e. the resources will be
145 leveled.
146
147 * Assign resources
148 The next step is to list all the resources working on the project and
149 assign the tasks to them. Create a node for the resources. You can
150 group the resources by creating hierarchies. Tag the resource tree
151 with the tag ~taskjuggler_resource~ so that the exporter knows where to
152 look for resource definitions[fn:2].
153
154 #+BEGIN_SRC org
155 ,* Resources                                         :taskjuggler_resource:
156 ,** Developers
157    :PROPERTIES:
158    :resource_id: dev
159    :END:
160 ,*** Paul Smith
161     :PROPERTIES:
162     :resource_id: paul
163     :END:
164 ,*** Sébastien Bono
165     :PROPERTIES:
166     :resource_id: seb
167     :END:
168 ,*** Klaus Müller
169
170 ,** Others
171 ,*** Peter Murphy
172     :PROPERTIES:
173     :resource_id: doc
174     :END:
175 ,*** Dim Sung
176     :PROPERTIES:
177     :resource_id: test
178     :END:
179 #+END_SRC
180
181 As you'll note I also added some ~resource_id~ properties to some of
182 the resources (or resource groups). I will use these identifiers to
183 allocate the resources to the tasks. The exporter will create unique
184 ids for the resources automatically[fn:3], but if you want to use
185 short forms it's better to define ~resource_id~ properties for your
186 resources. This will also allow you to define default values for the
187 allocation as follows:
188
189 : #+PROPERTY: allocate_ALL dev doc test
190
191 The easiest way to assign resources is again the column view mode.
192 There is no need to allocate a resource to every task, as allocations
193 are inherited in TaskJuggler[fn:4]. You'll note in the screen shot
194 below that some tasks have more than one resource assigned to them.
195 TaskJuggler will calculate the duration of the task based on the
196 effort and the resources working on this task.
197
198 #+CAPTION: Assign resources
199 #+ATTR_HTML: alt="Assign resources"
200 [[file:../images/taskjuggler/assign-resources.png]]
201
202 If we now export the project you'll see that TaskJuggler scheduled
203 some tasks in parallel (as there are several resources now which can
204 work in parallel). See the screen shot below:
205
206 #+CAPTION: Gantt Chart with multiple resources
207 #+ATTR_HTML: alt="Gantt Chart with multiple resources"
208 [[file:../images/taskjuggler/TaskJugglerUI2.png]]
209
210 Obviously we need to define dependencies between the tasks.
211
212 * Define dependencies
213 There are several ways to define dependencies between tasks. When
214 coming from an Org mode background you probably want to define them
215 using the facilities provided by Org mode, which are either 
216
217   - The =ORDERED= property which allows you to state that the child
218     tasks have to be completed in the order they appear (top most
219     first).
220
221   - The =BLOCKER= property which allows you to state that a task
222     depends on either
223     - a previous sibling ("previous-sibling") or 
224     - any other task by stating the ~task_id~ property of the
225       predecessor
226
227 Again, it is probably easiest to define the dependencies using the
228 column view as shown below in the screen shot:
229
230 #+CAPTION: Defining dependencies using column view 
231 #+ATTR_HTML: alt="Defining dependencies using column view"
232 [[file:../images/taskjuggler/define-dependencies.png]]
233
234 Lastly there is also the ~depends~ property which corresponds to the
235 TaskJuggler terminology. It can be used the same way as the =BLOCKER=
236 property. This is illustrated below where the "Software Development"
237 for example is blocked by the task "Specification", i.e. it has to
238 wait until the specification is done. The task "Software Development"
239 is defined as =ORDERED=, i.e. all the subtasks of it have to be
240 completed in sequence. Another example is the milestone "Ship Product
241 to Customer" which is waiting until the Beta test and the Manual are
242 done.
243
244 #+BEGIN_SRC org
245 ,#+PROPERTY: Effort_ALL 2d 5d 10d 20d 30d 35d 50d 
246 ,#+PROPERTY: allocate_ALL dev doc test
247 ,#+COLUMNS: %30ITEM(Task) %Effort %allocate %BLOCKER %ORDERED
248
249 ,* Accounting Software                                        :taskjuggler_project:
250
251 ,** Specification
252    :PROPERTIES:
253    :Effort:   20d
254    :BLOCKER:  start
255    :allocate: dev
256    :END:
257
258 ,** Software Development
259    :PROPERTIES:
260    :ORDERED:  t
261    :BLOCKER:  previous-sibling
262    :priority: 1000
263    :allocate: dev
264    :END:
265
266 ,*** Database coupling
267     :PROPERTIES:
268     :Effort:   20d
269     :END:
270
271 ,*** Back-End Functions
272     :PROPERTIES:
273     :Effort:   30d
274     :task_id:  back_end
275     :END:
276
277 ,*** Graphical User Interface
278     :PROPERTIES:
279     :Effort:   35d
280     :allocate: paul, seb
281     :END:
282
283 ,** Software testing
284    :PROPERTIES:
285    :ORDERED:  t
286    :BLOCKER:  previous-sibling
287    :allocate: test
288    :END:
289 ,*** Alpha Test
290     :PROPERTIES:
291     :Effort:   5d
292     :task_id:  alpha
293     :END:
294
295 ,*** Beta Test
296     :PROPERTIES:
297     :Effort:   20d
298     :task_id:  beta
299     :allocate: test, paul
300     :END:
301
302 ,** Manual
303    :PROPERTIES:
304    :Effort:   50d
305    :task_id:  manual
306    :BLOCKER:  start
307    :allocate: doc
308    :END:
309
310 ,** Milestones
311 ,*** Project start
312     :PROPERTIES:
313     :task_id:  start
314     :END:
315
316 ,*** Technology Preview
317     :PROPERTIES:
318     :BLOCKER:  back_end
319     :END:
320
321 ,*** Beta version
322     :PROPERTIES:
323     :BLOCKER:  alpha
324     :END:
325
326 ,*** Ship Product to Customer
327     :PROPERTIES:
328     :BLOCKER:  beta manual
329     :END:
330
331
332 ,* Resources                                         :taskjuggler_resource:
333 ,** Developers
334    :PROPERTIES:
335    :resource_id: dev
336    :END:
337 ,*** Paul Smith
338     :PROPERTIES:
339     :resource_id: paul
340     :END:
341 ,*** Sébastien Bono
342     :PROPERTIES:
343     :resource_id: seb
344     :END:
345 ,*** Klaus Müller
346
347 ,** Others
348 ,*** Peter Murphy
349     :PROPERTIES:
350     :resource_id: doc
351     :limits:   { dailymax 6.4h }
352     :END:
353 ,*** Dim Sung
354     :PROPERTIES:
355     :resource_id: test
356     :END:
357 #+END_SRC
358
359 If you export the example above you'll TaskJuggler will schedule the
360 tasks as shown in the screen shot below
361
362 #+CAPTION: Gantt Chart with dependencies
363 #+ATTR_HTML: alt="Gantt Chart with dependencies"
364 [[file:../images/taskjuggler/TaskJugglerUI3.png]]
365
366 Also TaskJuggler will give you a overview how busy youre resources
367 will be and what they are working on. See below for a screen shot:
368
369 #+CAPTION: Resource usage chart
370 #+ATTR_HTML: alt="Resource usage chart"
371 [[file:../images/taskjuggler/resource-graph.png]]
372
373 Finally you can generate [[file:../images/taskjuggler/project-plan.pdf][good-looking project plans]] in PDF by printing
374 from TaskJuggler. This will make any [[http://en.wikipedia.org/wiki/Pointy-haired_Boss][Pointy-haired Boss]] happy.
375
376 * Export of other properties
377 Generally the exporter writes a node property that is known to
378 TaskJuggler (such as ~shift~, ~booking~, ~efficiency~, ~journalentry~,
379 ~rate~ for resources or ~account~, ~start~, ~note~, ~duration~, ~end~,
380 ~journalentry~, ~milestone~, ~reference~, ~responsible~, ~scheduling~,
381 etc for tasks) as is to the TaskJuggler file.
382
383 Other properties such as completeness or priority are derived from
384 implicit information in the Org mode file. The TODO state for example
385 determines the completeness. A task will be exported with 100%
386 complete (~complete 100~) if it is marked as done. The priority of a
387 task will be determined through its priority cookie.
388
389
390 * Footnotes
391 [fn:1] You can customize this tag
392
393 [fn:2] Again, of course this tag can be customized
394
395 [fn:3] by downcasing the headline, replacing non-ascii characters with
396 '_' and picking the first word if it is unique
397
398 [fn:4] In TaskJuggler the allocations are cumulative, the exporter
399 however adds some code so that inherited allocation are ignored when
400 explicitly assigning a resource.
401