Created placeholder for the to-be-filled-in Taskjuggler 3 tutorial. At the present...
[worg.git] / org-tutorials / org-taskjuggler3.org
1 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil 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:      Exporting Gantt charts with Taskjuggler v3 (tj3)
6 #+AUTHOR:     John Henderson
7 #+EMAIL:      jw DOT hendy AT gmail DOT com
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
17 This article discusses the use of [[http://orgmode.org/][Org-mode]] for project planning using [[http://www.taskjuggler.org/][Taskjuggler]],
18 self-described as follows (from the project website):
19
20 #+begin_quote
21 TaskJuggler is a modern and powerful, Free and Open Source Software project management
22 tool. Its new approach to project planning and tracking is more flexible and superior to
23 the commonly used Gantt chart editing tools. 
24 #+end_quote
25
26 A [[http://orgmode.org/worg/org-tutorials/org-taskjuggler.html][tutorial already exists]] for the use of Org-mode and Taskjuggler v2.4.3, the last release of the
27 v2.x.x series. Taskjuggler Version 3 (often referred to as simply "tj3"), was rebuilt using [[http://www.ruby-lang.org/en/][Ruby]], and no
28 longer features the former [[http://qt-project.org/][Qt]]-based GUI for task/timeline management of a project.
29
30 It should also be mentioned that the project is now [[http://www.taskjuggler.org/manual/change_log.html#version_1_0_0][10 years old]], and, as a result, is
31 [[http://taskjuggler.org/tj3/manual/toc.html][fantastically documented]]. 
32
33 The [[http://orgmode.org/manual/TaskJuggler-export.html][Org-mode manual coverage of Taskjuggler]] covers Taskjuggler export to some extent,
34 however the defaults assume the use of version 2.x.x. This tutorial will lay out
35 the changes required to successfully export with tj3.
36
37 * Installation and Setup
38
39 *Preface:* If you have not recently (and successfully) used tj3, it is recommended that you
40 try compiling the example =.tjp= file as described below to rule out any issues with the
41 tj3 installation itself before moving on integrating tj3 with Org mode.
42
43 Please refer to the [[http://taskjuggler.org/tj3/manual/Installation.html#Installation][installation section]] of the Taskjuggler manual for instructions. For
44 the high level overview, you will need to install =ruby= and possibly =ruby-gems=. The
45 easiest method is probably to install =ruby-gems= and simply type, from a
46 terminal/command-line interface (you may need to run this as the =root= user or with =sudo=):
47
48 #+begin_example
49
50 gem install taskjuggler
51
52 #+end_example
53
54 For Linux users, you may have a distro-specific package available if you would rather choose that
55 route. For example, the Arch Linux User Repository ([[https://aur.archlinux.org/][AUR]]) has a [[https://aur.archlinux.org/packages/taskjuggler3/][Taskjuggler 3 package]] available.
56
57 Once installed, you should check functionality by typing:
58
59 #+begin_example 
60
61 tj3 --version
62
63 #+end_example
64
65 If you just can't wait to see what tj3 can do, try compiling their [[http://taskjuggler.org/tj3/examples/Tutorial/tutorial.tjp][sample file]]:
66
67 - Copy/paste into a file called =something.tjp=. Alternatively, 
68
69 #+begin_example
70
71 http://taskjuggler.org/tj3/examples/Tutorial/tutorial.tjp
72
73 #+end_example
74
75 - Save the file and then issue:[fn:1]
76
77 #+begin_example
78
79 $ cd /path/to/something.tjp
80 $ tj3 something.tjp
81
82 #+end_example
83
84 Now check out the generated =Overview.html= in a browser!
85
86 * Using tj3 with Org mode
87
88 /Details to come [shortly]!/
89
90 * Footnotes
91
92 [fn:1] You may run into compilation issues due to special characters in that file on
93 lines 37 (a copyright symbol), 79, and 83 (two accented characters in resource names). If
94 this happens, just replace those three characters with something else, or delete them,
95 and the file should compile. [[https://github.com/taskjuggler/TaskJuggler/issues/105][An issue has been filed]] inquiring about whether or not this
96 is a system setup issue and, if not, suggesting that the characters be replaced.
97
98 * TODO Fill in the details!                                        :noexport:
99 ** Plan your project
100 You start out as you normally would by breaking down the project into
101 tasks. Let's take the following example where you have a project to
102 create an accounting software:
103
104 #+BEGIN_SRC org
105 ,* Accounting Software
106
107 ,** Specification
108
109 ,** Software Development
110 ,*** Database coupling
111 ,*** Back-End Functions
112 ,*** Graphical User Interface
113
114 ,** Software testing
115 ,*** Alpha Test
116 ,*** Beta Test
117
118 ,** Manual
119
120 ,** Milestones
121 ,*** Project start
122 ,*** Technology Preview
123 ,*** Beta version
124 ,*** Ship Product to Customer
125 #+END_SRC
126
127 ** Estimate the effort
128 Now that you've figured out the tasks it's time to estimate the
129 efforts for each task. By using column view this can be done very
130 efficiently. It also helps to define the =COLUMNS= and default values
131 for the Effort property as shown in the following screen shot:
132
133 #+CAPTION: Estimating effort using column view 
134 #+ATTR_HTML: alt="Estimating effort using column view"
135 [[file:../images/taskjuggler/effort-estimation.png]]
136
137 Your resulting Org mode project file will look somewhat like the
138 following:
139
140 #+BEGIN_SRC org
141 ,#+PROPERTY: Effort_ALL 2d 5d 10d 20d 30d 35d 50d 
142 ,#+COLUMNS: %70ITEM(Task) %Effort
143
144 ,* Accounting Software
145
146 ,** Specification
147    :PROPERTIES:
148    :Effort:   20d
149    :END:
150
151 ,** Software Development
152
153 ,*** Database coupling
154     :PROPERTIES:
155     :Effort:   20d
156     :END:
157
158 ,*** Back-End Functions
159     :PROPERTIES:
160     :Effort:   30d
161     :END:
162
163 ,*** Graphical User Interface
164     :PROPERTIES:
165     :Effort:   35d
166     :END:
167
168 ,** Software testing
169 ,*** Alpha Test
170     :PROPERTIES:
171     :Effort:   5d
172     :END:
173
174 ,*** Beta Test
175     :PROPERTIES:
176     :Effort:   20d
177     :END:
178
179 ,** Manual
180    :PROPERTIES:
181    :Effort:   50d
182    :END:
183
184 ,** Milestones
185 ,*** Project start
186 ,*** Technology Preview
187 ,*** Beta version
188 ,*** Ship Product to Customer
189 #+END_SRC
190
191 ** Generate a Gantt chart
192 Before you now export the project to TaskJuggler you need to tell the
193 exporter in which tree it can find the tasks. You do this by adding
194 the tag ~taskjuggler_project~ to the node "Accounting Software"[fn:2].
195 Do this by moving to the "Accounting Software" headline and typing the
196 following:
197
198 : C-c C-c taskjuggler_project RET
199
200 This allows you to have other nodes for this project such as an
201 introduction or general notes.
202
203 To export the project to TaskJuggler you simply type 
204
205 : M-x org-export-as-taskjuggler-and-open
206
207 This will open your project in TaskJugglerUI as illustrated below
208
209 #+CAPTION: Gantt chart in TaskJugglerUI
210 #+ATTR_HTML: alt="Gantt chart in TaskJugglerUI"
211 [[file:../images/taskjuggler/TaskJugglerUI1.png]]
212
213 Since we have not assigned any resources to work on the project the
214 exporter assumes that you will be the one working on it and has
215 assigned all tasks to you. The tasks have been serialized so that you
216 will not have to many things to do at once, i.e. the resources will be
217 leveled.
218
219 ** Assign resources
220 The next step is to list all the resources working on the project and
221 assign the tasks to them. Create a node for the resources. You can
222 group the resources by creating hierarchies. Tag the resource tree
223 with the tag ~taskjuggler_resource~ so that the exporter knows where to
224 look for resource definitions[fn:3].
225
226 #+BEGIN_SRC org
227 ,* Resources                                         :taskjuggler_resource:
228 ,** Developers
229    :PROPERTIES:
230    :resource_id: dev
231    :END:
232 ,*** Paul Smith
233     :PROPERTIES:
234     :resource_id: paul
235     :END:
236 ,*** Sébastien Bono
237     :PROPERTIES:
238     :resource_id: seb
239     :END:
240 ,*** Klaus Müller
241
242 ,** Others
243 ,*** Peter Murphy
244     :PROPERTIES:
245     :resource_id: doc
246     :END:
247 ,*** Dim Sung
248     :PROPERTIES:
249     :resource_id: test
250     :END:
251 #+END_SRC
252
253 As you'll note I also added some ~resource_id~ properties to some of
254 the resources (or resource groups). I will use these identifiers to
255 allocate the resources to the tasks. The exporter will create unique
256 ids for the resources automatically[fn:4], but if you want to use
257 short forms it's better to define ~resource_id~ properties for your
258 resources. This will also allow you to define default values for the
259 allocation as follows:
260
261 : #+PROPERTY: allocate_ALL dev doc test
262
263 The easiest way to assign resources is again the column view mode.
264 There is no need to allocate a resource to every task, as allocations
265 are inherited in TaskJuggler[fn:5]. You'll note in the screen shot
266 below that some tasks have more than one resource assigned to them.
267 TaskJuggler will calculate the duration of the task based on the
268 effort and the resources working on this task.
269
270 #+CAPTION: Assign resources
271 #+ATTR_HTML: alt="Assign resources"
272 [[file:../images/taskjuggler/assign-resources.png]]
273
274 If we now export the project you'll see that TaskJuggler scheduled
275 some tasks in parallel (as there are several resources now which can
276 work in parallel). See the screen shot below:
277
278 #+CAPTION: Gantt Chart with multiple resources
279 #+ATTR_HTML: alt="Gantt Chart with multiple resources"
280 [[file:../images/taskjuggler/TaskJugglerUI2.png]]
281
282 Obviously we need to define dependencies between the tasks.
283
284 ** Define dependencies
285 There are several ways to define dependencies between tasks. When
286 coming from an Org mode background you probably want to define them
287 using the facilities provided by Org mode, which are either 
288
289   - The =ORDERED= property which allows you to state that the child
290     tasks have to be completed in the order they appear (top most
291     first).
292
293   - The =BLOCKER= property which allows you to state that a task
294     depends on either
295     - a previous sibling ("previous-sibling") or 
296     - any other task by stating the ~task_id~ property of the
297       predecessor
298
299 Again, it is probably easiest to define the dependencies using the
300 column view as shown below in the screen shot:
301
302 #+CAPTION: Defining dependencies using column view 
303 #+ATTR_HTML: alt="Defining dependencies using column view"
304 [[file:../images/taskjuggler/define-dependencies.png]]
305
306 Lastly there is also the ~depends~ property which corresponds to the
307 TaskJuggler terminology. It can be used the same way as the =BLOCKER=
308 property. This is illustrated below where the "Software Development"
309 for example is blocked by the task "Specification", i.e. it has to
310 wait until the specification is done. The task "Software Development"
311 is defined as =ORDERED=, i.e. all the subtasks of it have to be
312 completed in sequence. Another example is the milestone "Ship Product
313 to Customer" which is waiting until the Beta test and the Manual are
314 done.
315
316 #+BEGIN_SRC org
317 ,#+PROPERTY: Effort_ALL 2d 5d 10d 20d 30d 35d 50d 
318 ,#+PROPERTY: allocate_ALL dev doc test
319 ,#+COLUMNS: %30ITEM(Task) %Effort %allocate %BLOCKER %ORDERED
320
321 ,* Accounting Software                                        :taskjuggler_project:
322
323 ,** Specification
324    :PROPERTIES:
325    :Effort:   20d
326    :BLOCKER:  start
327    :allocate: dev
328    :END:
329
330 ,** Software Development
331    :PROPERTIES:
332    :ORDERED:  t
333    :BLOCKER:  previous-sibling
334    :priority: 1000
335    :allocate: dev
336    :END:
337
338 ,*** Database coupling
339     :PROPERTIES:
340     :Effort:   20d
341     :END:
342
343 ,*** Back-End Functions
344     :PROPERTIES:
345     :Effort:   30d
346     :task_id:  back_end
347     :END:
348
349 ,*** Graphical User Interface
350     :PROPERTIES:
351     :Effort:   35d
352     :allocate: paul, seb
353     :END:
354
355 ,** Software testing
356    :PROPERTIES:
357    :ORDERED:  t
358    :BLOCKER:  previous-sibling
359    :allocate: test
360    :END:
361 ,*** Alpha Test
362     :PROPERTIES:
363     :Effort:   5d
364     :task_id:  alpha
365     :END:
366
367 ,*** Beta Test
368     :PROPERTIES:
369     :Effort:   20d
370     :task_id:  beta
371     :allocate: test, paul
372     :END:
373
374 ,** Manual
375    :PROPERTIES:
376    :Effort:   50d
377    :task_id:  manual
378    :BLOCKER:  start
379    :allocate: doc
380    :END:
381
382 ,** Milestones
383 ,*** Project start
384     :PROPERTIES:
385     :task_id:  start
386     :END:
387
388 ,*** Technology Preview
389     :PROPERTIES:
390     :BLOCKER:  back_end
391     :END:
392
393 ,*** Beta version
394     :PROPERTIES:
395     :BLOCKER:  alpha
396     :END:
397
398 ,*** Ship Product to Customer
399     :PROPERTIES:
400     :BLOCKER:  beta manual
401     :END:
402
403
404 ,* Resources                                         :taskjuggler_resource:
405 ,** Developers
406    :PROPERTIES:
407    :resource_id: dev
408    :END:
409 ,*** Paul Smith
410     :PROPERTIES:
411     :resource_id: paul
412     :END:
413 ,*** Sébastien Bono
414     :PROPERTIES:
415     :resource_id: seb
416     :END:
417 ,*** Klaus Müller
418
419 ,** Others
420 ,*** Peter Murphy
421     :PROPERTIES:
422     :resource_id: doc
423     :limits:   { dailymax 6.4h }
424     :END:
425 ,*** Dim Sung
426     :PROPERTIES:
427     :resource_id: test
428     :END:
429 #+END_SRC
430
431 If you export the example above you'll TaskJuggler will schedule the
432 tasks as shown in the screen shot below
433
434 #+CAPTION: Gantt Chart with dependencies
435 #+ATTR_HTML: alt="Gantt Chart with dependencies"
436 [[file:../images/taskjuggler/TaskJugglerUI3.png]]
437
438 Also TaskJuggler will give you a overview how busy youre resources
439 will be and what they are working on. See below for a screen shot:
440
441 #+CAPTION: Resource usage chart
442 #+ATTR_HTML: alt="Resource usage chart"
443 [[file:../images/taskjuggler/resource-graph.png]]
444
445 Finally you can generate [[file:../images/taskjuggler/project-plan.pdf][good-looking project plans]] in PDF by printing
446 from TaskJuggler. This will make any [[http://en.wikipedia.org/wiki/Pointy-haired_Boss][Pointy-haired Boss]] happy.
447
448 ** Export of other properties
449 Generally the exporter writes a node property that is known to
450 TaskJuggler (such as ~shift~, ~booking~, ~efficiency~, ~journalentry~,
451 ~rate~ for resources or ~account~, ~start~, ~note~, ~duration~, ~end~,
452 ~journalentry~, ~milestone~, ~reference~, ~responsible~, ~scheduling~,
453 etc for tasks) as is to the TaskJuggler file.
454
455 Other properties such as completeness or priority are derived from
456 implicit information in the Org mode file. The TODO state for example
457 determines the completeness. A task will be exported with 100%
458 complete (~complete 100~) if it is marked as done. The priority of a
459 task will be determined through its priority cookie.
460
461
462 ** Old footnotes
463 [fn:2] You can customize this tag
464
465 [fn:3] Again, of course this tag can be customized
466
467 [fn:4] by downcasing the headline, replacing non-ascii characters with
468 '_' and picking the first word if it is unique
469
470 [fn:5] In TaskJuggler the allocations are cumulative, the exporter
471 however adds some code so that inherited allocation are ignored when
472 explicitly assigning a resource.