Project management all in plain text
Taking “Your Life in Plain Text” to the extreme, Aaron Peters shows how to manage complex projects with Emacs Org-mode.
Org-mode’s motto is, “Your Life in Plain Text”, and in LXF241 we took a look at how you could use Org-mode to author and publish a writing project, such as that Linux Format article itself (sort of like getting an OS to finally compile itself?). We also touched on Org-mode’s ability to manage tasks, i.e. items that are either to-do or done. In this article we’ll look at Org-mode’s more sophisticated projectmanagement functions.
Org-mode tasks
Before proceeding, let’s briefly review tasks at a basic level. Org-mode considers any line starting with one or more asterisks (followed by a single space) to be a *headline*. Headlines, among other things, can be assigned a status and thereby made into a task.
By default, you can rotate a headline through the following three states: blank (no status, it’s just a headline); *TODO* (a task, but not yet completed); and *DONE*. The keybinding Shift-left and Shift-right cycle through this order backwards and forwards, respectively; in addition the command *org-todo* will cycle forward only.
For the purpose of this article, when we refer to a “task” it implies that it’s an Org-mode headline with an assigned status. We’ll also cite the formal Org-mode commands in the article, but we’ll provide a summary of them with their associated keyboard shortcuts at the end. This alone gives you the ability to assemble functional if simple task lists. But you’re not here for simple are you?
Break it down
A basic part of project management is to break down large initiatives into smaller pieces that can be delegated, easily understood, and achieved. In Orgmode terms this means taking high-level headlines and creating sub-headlines beneath them.
Looking back at LXF241, we see that adding asterisks to the start of the line indents headlines. So for a large task such as writing this article, we can break it down into some distinct sub-items, as follows:
* Advanced Project Management in Org-mode ** Outline the Project Management Process
** List Relevant Org-mode Features
** Draft Article Text
** Take & Crop Screenshots
** Format for Submission
Adding these as sub-tasks enables you to attack your project in manageable chunks. Org-mode also supports a ‘roll-up’ of your sub-task progress. If you append [/] to the end of a task that contains sub-tasks, it will begin to track the number completed versus the
total number. Using [%] instead will express it as a percentage instead of a fraction. Note that the completion of sub-tasks will update the progress of the parent task, but not change its actual status (at least not by default).
Set it back up
Once you have your project broken down into multiple, smaller parts, one way to approach it is to do one part at a time, in order, until they are all completed. However, this isn’t always feasible. It’s therefore useful to know which tasks need to be completed before others can begin. In the world of suits, this is referred to as a /predecessor/ relationship, and you can specify these using Org-mode properties.
Properties are attributes of a particular headline. You can use the *org-set-property* command to add one to your current headline (see the sidebar for more detail on Properties syntax). The /ORDERED/ and /BLOCKER/ properties are two such, and they’ll help us to designate our dependency structure. ORDERED is assigned to a parent task, and indicates that all its children need to be completed in the order in which they appear. BLOCKER, on the other hand, is assigned to a parent or child, and indicates the task that must be completed before that task can begin. The value you assign to the BLOCKER property must be either /start/, meaning the start of the project, /previoussibling/, which means the task before within the same parent, or an ID of another task in the project (as assigned using the /TASK_ID/).
What an effort
Now you have a rough idea of when things need to happen in relation to one another. The next part of this formula is knowing how long they’ll take. You can add work estimates using the /EFFORT/ property containing a time frame, either in H:MM notation or with a whole number followed by m (minutes), h (hours), d (days), or w (weeks).
EFFORT is useful to plan the project, but it’s good practice to also record your time. When you start working on a task, place the cursor on its headline, and use the command *org-clock-in* to start a timer. When you’ve finished, use *org-clock-out*. You can continue to do this throughout the day as well as daily for longer tasks, and Org-mode will keep a running tally of the total clocked time.
This record is called the /LOGBOOK/, and it’s created directly below the Properties drawer for the headline if one exists. This is another expandable and collapsible (with the Tab key) region that will contain a list of all the time logs you’ve created for that task. They’re listed with the newest entry on top. If you’d like a tally of all the time in a nicely formatted report, you can choose a place in the Org-mode file and use the *org-clock-report* command to insert a block that lists all the tasks with the clocked time you have to date. This is what’s called a /dynamic block/ in Org-mode, and as you add time to your various tasks, you can place the cursor within the block and use the command *orgdblock-update* to automatically fill in revised tasks as well as add new ones with clocked time.
It’s time to start figuring out when you’ll need to do the tasks in your project in order to get it done. But you may find it’s becoming difficult to get a view of your project that you can use to plan effectively – at least in the default “plain text” view of your Org-mode document. It’s time to set up something more usable, called /Columns View/. This will enable you to view tasks in a table that you can then use to update the values of properties.
Add the following line at the start of your document: #+COLUMNS: %40ITEM(TASK) %8EFFORT %ORDERED %BLOCKER{+}
These items, starting with a % symbol, describe what the columns in your table will contain. The number afterwards, if present, is how many spaces wide the column will be. Otherwise the column is sized automatically. The next item will be the column’s contents, which you can see here include the /ITEM/ itself, the property /EFFORT/, the property /ORDERED/, and the property /BLOCKER/ as we configured them in the last section. If you’d like something else to appear in the column header, you can include it in brackets. Once this is set up, place the cursor above the first Level-1 task in your plan, and use the command *org-columns* to switch the document to Columns View. Press the Q key to exit it.
As you will see, this gives you a much better look at your plan. With the dependencies and effort in place, we can now get on with actually scheduling the tasks. Start by adding two additional properties, /SCHEDULED/ and /DEADLINE/, which will let us know when we’re supposed to work on a particular task and when it will need to be completed, respectively.
While you’re there, add columns for the /TODO/ status as well as the /CLOCKSUM/, so that you can see any time you have logged to your tasks to round out the picture:
#+COLUMNS: %40ITEM(TASK) %TODO %8EFFORT %CLOCKSUM %SCHEDULED %DEADLINE %ORDERED %BLOCKER{+}
After adding these columns, you can start to fill in their values directly from Columns View. Using the arrow keys to move over to the /SCHEDULED/ column of the first task, press the E key. This is the key that enables you to edit the contents of the cell. But look – at the bottom of the window, a calendar will appear. Because this property is known to hold dates, clicking a date on the calendar will insert the value in correct Orgmode datestamp format. Not too shabby for a plain text program, eh?
It’s all busy work
While the actual amount of work something will take is /effort/, how long that work will span on a calendar is referred to as /duration/. There’s a reason these two aren’t the same thing. You may estimate that one task will take you four hours to complete. However, if you have other responsibilities that only leave you with two hours a day to dedicate to that task, then the duration of that task will be two days.
This is where the /SCHEDULED/ and /DEADLINE/ special properties come in. Knowing that a task will begin on, say, 20 December, and that it will require two days, you can set its /SCHEDULED/ date for that day and its /DEADLINE/ as 21 December. Then provided the next task is dependent on the first, you can set the /SCHEDULED/ start date for it on the following day, and its /DEADLINE/ to accommodate the /EFFORT/ it requires. In this way, you can build a plan for all the tasks in your project, assign their schedule, and easily review them in Column View to see what’s next. You can add these values with the *org-schedule* and *orgdeadline* commands, respectively, and they’ll appear between the task headline and the Properties drawer.
Sharing & collaborating
But what if you want to communicate this to others in a team? What if you need to collaborate with others? For example, updating teammates or managers on a project’s progress? Fortunately, as the old Emacs credo goes, “There’s a package for that!” A great way to share your project with others is through the use of a Gantt chart, which will:
Display all the tasks in the project
Illustrate their dependencies, if any
Show when they’re scheduled to start and end Demonstrate any progress made
And, by coincidence, these are all the things we’ve spent all this time configuring! There are a couple of different options to produce Gantt charts from Orgmode source, but for this example we’ll use the
Taskjuggler tool. While this was once a GUI application in the same vein as Ganttproject or Calligra Plan, it’s now a package of terminal programs with an optional server. But in this case, we’ll simply use the package’s *org-taskjuggler* commands to do the heavy lifting for us. This package should be included with most Orgmode distributions, and since Org-mode is included in
Emacs by default in recent versions, chances are you already have it. Try searching for the exporter by using M-x to bring up the command buffer, then type in “taskjuggler.” If options remain, you’re all set on the
Emacs side.
Next, make sure Taskjuggler is installed. On Ubuntu, this is easy from the terminal: sudo apt install tj3
As it’s a Ruby program, you can also install the
Taskjuggler gem if that’s your preference: gem install taskjuggler
Use the magic M-x (Alt-x) keystroke and enter: *org-taskjuggler-export-process-and-open*
This will do a couple of things in the same directory as your Org file:
1 It will export your Org file to a TJP file, which is the standard Taskjuggler format.
2 It will process your TJP file, scheduling your tasks according to what resources are available (by default, it’s just yourself) and how much time you have.
3 It will generate a report containing charts for both the projects schedule (this is your Gantt chart) and your resource allocation in a folder called Reports.
Note that Taskjuggler’s main functionality is in the second step, meaning that it’s better suited to projects where you’ll let it handle decisions like start and end dates based on the effort estimates you provide. It can even manage your team’s workload by including information on your resource capacity (in Org-mode format, of course). To learn more about this, the Worg site has a great tutorial on the subject, visit http://bit. ly/lxf60worg.
If Taskjuggler doesn’t seem like it’ll fit your needs, there are a couple of other ways you can plan in Orgmode and collaborate with others:
The *org-gantt* (https://github.com/swillner/orggantt) package is similar to Taskjuggler but standalone in the sense it doesn’t require an external program.
Using *org-trello* (https://orgtrello.github.io) will enable you to fetch and update the Trello cards the rest of your team uses.
For development activities, *org-jira* (https://github. com/ahungry/org-jira) synchronises with the popular Atlassian product.
The *org-todoist* package (https://github.com/ ttakamura/org-todoist) will likewise sync with this popular online task management tool.
Advanced project management
In this article we’ve described how you can take your project’s plan from a high level (e.g. just a collection of major steps) to something detailed that you can conquer one piece at a time. But how would you actually use it in practice? Consider the following:
You’re leading an open source team implementing a new feature. With your team, you decide to break it
down into several components, then discuss the steps you’ll need to develop each one.
2 You start by creating a plan in Org-mode outlining these phases, their tasks and sub-tasks. You then also add assignees.
3 Using Taskjuggler, you can export the project schedule. Everyone can see the overall plan, and each team member actually gets their own personalised one in the Resource Allocation chart.
4 Periodically (perhaps every day, or every week) you check in with the team and record the progress made on their tasks.
5 You adjust the Org-mode plan with this data, using Column View to jump around easily and update fields.
6 Once you have all the updates, you re-publish the project schedule and everyone gets back to work.
Hopefully, you’re not under the directive of corporate overlords to use some proprietary, cloud-based system, because Org-mode is entirely capable of keeping you (and a team, if you have one) on track to meet and achieve your goals.