DWP Advice for decision making in HTML

Update: for anyone who found the monolithic version troublesome, there’s a lightweight multiple file edition at https://www.lampfrey.net/adm/light

The DWP publishes the Advice for decision making, or ADM. The ADM is not a statement of law, but it contains official guidance used by DWP staff to interpret and implement the law. It covers the benefits brought in by the 2012 Welfare Reform Act:

  • universal credit
  • personal independence payments
  • new style employment and support allowance
  • new style jobseeker’s allowance

The ADM runs to a couple of thousand pages, divided into volumes, chapters and numbered paragraphs. This structure has been somewhat obscured by the transfer to .GOV.UK – the ADM is presented as a string of PDFs, each holding one chapter, but the distinction between volumes has been lost.

Unfortunately, although the ADM is highly self-referential, there are no links between paragraphs. It’s especially awkward to follow references across the 100 or so chapters. A typical paragraph looks like this:


As an experiment, I decided to make an HTML version with functioning links. Because I was building it primarily for myself, I didn’t have to worry too much about:

  • visual appearance
  • standards
  • perfection

I wrote a set of scripts to:

  • scrape the ADM chapters from .GOV.UK
  • convert these into a single large PDF
  • extract this PDF into HTML
  • parse the raw HTML to insert links, add back references and expand acronyms

Resulting in output like this:


A single file

I originally just wrote out the ADM as a single HTML file. This has the following advantages:

  • it’s a thing – you can save it, email it, rehost it and reference individual paragraphs as URLs
  • the whole document can be searched using the browser’s find function

and the following disadvantages:

  • it’s big: some browsers and devices choke
  • as anyone can pass it on to anyone, I can’t track its use without additional effort. This is also an advantage.

I now have a version divided into chapters at https://www.lampfrey.net/adm/light/adm-contents.html

This should work in any current browser.

There are also several drawbacks to my general approach:

  • ripping open PDFs and parsing the resulting text is a fundamentally stupid way of doing things – but I don’t have access to whatever the originating format might be…
  • the parsing is imperfect and ad hoc – there are also a significant number of errors propagated from the source documents
  • the formatting is pretty rubbish – a consequence of the PDF -> HTML conversion
  • it doesn’t self update – it would be useful to have a built-in update check
  • I haven’t paid attention to accessibility
  • it doesn’t offer much contextual support – breadcrumbs, etc

Even so, for my purposes it’s far more usable than the original.

The single file version is here – please read the note on browsers and devices before opening .

A note on browsers and devices

The single file version works well on a mid-range Windows PC with

  • Chrome
  • IE10/11
  • Safari for Windows
  • Opera

It chokes (semi-randomly) using Firefox under Windows, but Firefox in Ubuntu is OK. Performance is tolerable using Chrome (but not Safari) on a recent iPhone. It fails to load on at least some Browser/Android combinations. Adblockers and other browser extensions which process links can increase the load time considerably.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>