As you know, today we launched the Government Digital Strategy. I’m part of the team that was tasked with putting these documents online, and from the outset we wanted to do it in a much more comprehensive way than simply uploading a PDF or a Word document. I’m going to explain a bit about how we put it together, from the perspective of a developer.
Making documents useful
We wanted the documents to exist online in a form that was both useful for readers and simple for the authors to work on collaboratively. We quickly agreed that sharing Markdown files would be a good approach.
Our first port of call was Jekyll, which is used at GDS extensively for prototyping sites and products, but it wasn’t quite right for what we needed here. While brilliant for turning Markdown files into a blog, Jekyll was going to struggle with our fairly complex documents. We turned instead to Kramdown, a Markdown parser written in Ruby which supports some useful extensions. Kramdown helped us as it:
- parses things Markdown doesn’t, including tables
- automatically generates a table of contents from headings on the page
- automatically generates IDs for headings
- gives us the ability to mark up content and give it extra classes or attributes
Publish, don’t send
The next question was how to share and manage the source documents. As a developer, my obvious first thought for anything to do with version management was using Git, with Github for sharing in public. We didn’t want everyone to have to learn how to use Git, but thankfully Github’s online interface allows Markdown files to be edited and committed from the site, eliminating that concern.
It was an interesting experience to see so many different people using Github’s interface to update the content, from hardened developers like myself to policy experts who were totally new to the service. There were a few bumps along the way, which was expected, but overall it was a really smooth experience.
Having these documents online and in the open is great, and the fact that Github keeps a history of these documents is good for transparency; over time, anyone can track the progress of the documents.
Assembling the strategy
Our build process is quite simple. Each document lives in its own folder as a series of Markdown files. We then build these by merging them into one Markdown file, running that through our very own Markdown pre-processor (which does some extra formatting), before they are finally run through the Kramdown compiler and outputted as HTML. I also built a very simple templating and partials system to avoid repeating content. All of this was integrated into a pretty straightforward shell script, meaning anyone who wants to see how it looks can simply run a small shell script and get everything generated for them. The script also handled our assets and produced a ‘built’ folder with everything neatly packaged up.
We used Sass (the “SCSS” variant) for styling, and RequireJS to manage our JavaScript. JavaScript was also used for the charts on the site, along with some clever CSS by Tim which turns regular tables into responsive bar charts.
This system was produced in just under three weeks. Whilst it’s very much geared to the documents published today, our next job is to extract the system into its own package that can then used by different teams for different documents and open-sourced onto Github.
There’s a fair bit of refactoring and reworking to be done, as there is on any system written in a short amount of time, but we’re looking forward to seeing what uses people find for it.
Filed under: Digital Strategy, GDS, Innovation
