Saturday, March 9, 2013

Markdoc as a Task Manager!

If you are familiar with Extreme Programming, you will be familiar with Backlog and Sprint as concepts. Otherwise a simple description is that Backlog is all the bits you have to build and Sprint is those bits from the Backlog that you are currently focusing on. These are usually expressed as short "user stories". Please don't tell me that I've over-generalised...I already know that!
So if I generalise further there's a lot to be said for those same sort of concepts applied to other kinds of projects - not just software development. I wrote previously about the excellent Markdoc wiki script and this use case uses that same script.
I first initialised a Markdoc wiki. The order is important here so do this first. I was intending to make it a Git repo so I used the "--vcs-ignore git" flag so it created its own .gitignore. Then I initialised it as a Git repo. The actual directory is inside Dropbox. Inside Markdoc's wiki directory I created 4 sub-directories:
  • backlog
  • active
  • blocked
  • done
Then I set up a remote repo on our server. These repos are managed by the wonderful Gitolite and that will later be important. This step allows others to clone, work on and then push their changes. Alternatively for users that don't work in Git we can share the Dropbox wiki directory with them so they can work in there.
Then on another user on the server I cloned the remote repo. This repo is the one where the Markdoc build takes place and where the web server serves from. The web root directory is the /.html directory in the repo. A launchd job runs a "git pull" at set intervals. If the remote repo has changed then the pull results in a merge and that in turn kicks off a post-merge hook which issues the "markdoc build" command which populates the /.html directory.


Web access is managed by a web server realm that limits access to group members and requires authentication.
So a couple of explanations are in order. Firstly why have both the remote repo and the repo on the web server? Why not just combine them? Two reasons. Firstly, by default, the remote repo is a bare repo and I think it's good practice to keep it like that. That means that there is no working directory and therefore nothing to run "markdoc build" against. Secondly gitolite fairly tightly manages ssh access to that user so it's not practical to configure and remotely manage the web server from that account.
The wasteful bit is the launchd job which runs, on the web server user, at fixed intervals regardless of whether there has been an update to the remote repo or not. I'm toying with ways of fixing that at the moment.
To use the system you populate your backlog directory with Markdown documents, one for each task. We use a fixed template so that we get all the info we need in each "task story". The first level 1 heading is a descriptive title for the task and this is shown on the web as the document's title.
As tasks become active they are moved to the /active directory and info about who is acting on the task and what the dates are is added.
If a task becomes blocked it's moved to blocked and a narrative explaining things is added. Finished tasks are moved to done.
Many task management systems rely on one line task descriptions. For complex jobs these descriptions are often not enough to keep everyone on the same page and to communicate intent. This system changes that. It also allows all of the team to see where the project is up to and it allows stakeholders to see exactly what's happening in the project.
If one of the directories - for instance /blocked - doesn't have anything in it then it's not shown on the wiki page on the web.
Lightweight, fast and flexible. There are dozens of other web systems for Scrum and XP but I've seen none as simple as this and as flexible for other projects. Tell me what you think.

1 comment: