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.