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.

Lightweight Continuous Documentation Build

You know this fixation we all have with the "document"? Yeah, that's the one, the one where we get all precious and don't want to show anyone the "document" until it's all nicely polished.
Well nuts to that!! I've been casting around for some time now to get a nice simple workflow that combines a Git repo with a lightweight wiki engine. I've finally got it up and working and happy. It's a bit of a sweet thing.
Here's how it works:

1. Write your stuff - you guessed it - in Markdown. Store the files in a Git repo.
2. Don't bother creating the "document". Instead break up what you are writing into manageable chunks and put each of those chunks into a file on its own.
3. Every now and then when you reach a point of wanting to go for a walk or running out of puff on what you are writing, do a commit in your repo. If you're not ready to show the world all of it then do a stash of the not-ready bits. But don't be too precious, this is about the conversation.
4. When you commit a post-commit hook runs. It does two things:
1. It issues a command "markdoc build". More on Markdoc in a minute.
2. It copies the resulting html files to the htdocs folder on the webserver.
5. The webserver serves your wiki content to the web.

It's really simple, really lightweight and really robust. Markdoc is the key component. It is a small Python script that takes the Markdown files and converts them to html and provides a tiny bit of structure. It can cope with a directory structure. It gives you back your html files along with a very simple directory listing "home page". Markdoc does this all with a two word command issued in Terminal on the Mac. It has an equally lightweight web server as part of the distro. Simply type "markdoc serve" and it will tell you where you can find the web pages with your browser.

I've chosen to ignore the built in server and instead I just copy the files across to the Mac server. That has a number of advantages. I can put the files for multiple wikis, each in their own directory, within the web root directory and serve from the web root directory. When I browse to the page I just get a directory listing, each of which is a wiki in its own right. When I open a wiki I get Markdoc's lightweight home page. It's very nice. Secondly I can use the Mac server's web hosting system to create a realm that requires access control. That means the wikis can be public or private as I please.

If I want to collaborate with someone on the writing, I don't do it on the wiki. That's only static html. Instead I get them to clone the Git repo and then push their changes back to the remote repo.

So why is this important? Well it means that we can share our progress with our team, our stakeholders and our collaborators. We don't get locked into "you'll have to wait for the next version of the document to see what's in it". Instead our team can see where we are up to, what we are thinking and where we have issues. It fosters discussion, collaboration and team work. It means we can't go off down a blind alley for too long before somebody notices; it means that people have a chance to see where we are going with our writing (and hence with the project) and to offer thoughts and ideas about how we might progress next.

It brings us one step closer to real-time collaboration. One step closer to breaking down the barriers that we've created, inadvertently, with the "document" and with our cumbersome tools. It allows us to step back in time using Git to reach a previous place if we realise we've drifted off track. It allows us to create a branch and work on an idea without fear of losing our work or getting confused. And all the while we are sharing our progress and sharing our ideas.

Very neat, it creates a very good working environment.

If you want some more details of the scripts and hooks let me know and I'll put them somewhere.