Over the past few months HMRC and GDS have collaborated on improving the way the HMRC manuals are maintained and made available to the public. HMRC publishes about 200 tax manuals which added up to about 80,000 pages on its former site. These manuals are mainly used by tax agents and other specialists for detailed tax guidance.
HMRC has built a new publishing system which makes it easier for its tax experts to update and maintain the content of the manuals. Tax agents, accountants and specialists need to be able to see the tax manuals exactly how HMRC publishes them internally, so the GDS team knew we couldn’t touch the content. We did create a new design for the manuals to make them more user-friendly and bring them in line with GDS design principles.
Between the backend and frontend sits the newly developed “write API” that allows HMRC editors to publish and update manuals on GOV.UK. This is a major milestone for GOV.UK; the first write API that allows a government organisation to publish directly to GOV.UK, something we'll be building on over the coming months.
VAT Government and Public Bodies is the first HMRC manual that is pushed from HMRC’s publishing system through our API and then published on GOV.UK.
It’s great to see the system working end-to-end as a beta but we’re not done yet.
We would like your feedback
The new version on GOV.UK and the old version on HMRC are currently running in parallel. We will keep both of them live for a couple of weeks to give you enough time to review and provide feedback. The best way to provide feedback is through the “Give feedback about this page” link at the top of each page or through our feedback form.
What’s next?
We will review your feedback carefully and continue iterating the format. Once we’re confident that the version on GOV.UK is accurate and meets the needs of our users we will redirect the HMRC version to GOV.UK.
In the coming weeks and months HMRC will import the remaining 200+ manuals into their new publishing system. After these imports have been carefully reviewed by HMRC’s tax experts the manuals will gradually be published and the old HMRC version redirected to GOV.UK.
Future development and improvements
We’ve previously blogged about the manuals format that we’re developing for all government departments. The GOV.UK product team is starting with a new round of iterations on this format and will look at things such as:
- search within a manual
- printing and downloading manuals
We will also apply these improvements to the HMRC manuals so that this format benefits from the work we’re doing for all government organisations.
36 comments
Comment by Stephen Edwards posted on
Great blog post but it would be well worth also publishing this on the HMRC blog: https://taxagents.blog.gov.uk or on the now defunct HMRC transition blog: https://hmrctransition.blog.gov.uk
The primary user need met by the Inside GOV.UK. blog is government publishers, which was why we originally set up the blogs I mentioned above, to meet the needs of end users not publishers. I don't expect there are many tax professionals who read this blog who also use this manual? Maybe I'm the only one, albeit I don't use this actual manual!
Comment by . posted on
How about navigation to the next page in the manual without having to keep pressing the back button
Comment by Neil Williams posted on
Yes, we agree and you will be pleased to know that's one of the next improvements we will be making. It's on our roadmap - see previous post on this blog if you want to see the roadmap in full https://insidegovuk.blog.gov.uk/2015/02/23/roadmap-update-monday-23rd-february/
Comment by Roo Reynolds posted on
FYI, we've recently added next & previous links (see https://www.gov.uk/hmrc-internal-manuals/vat-government-and-public-bodies/vatgpb1300 for example)
Comment by Kevin Ringer posted on
Why are Next and Previous so large?
Comment by Tim Blackwell posted on
Do you have a time-table for moving DWP guidance (Advice for Decision Making and Decision Maker's Guide) to the new format?
As a general principle, please don't turn off old resources until the functionality of the replacement is at least equivalent to that of the replaced. Being able to navigate a sequence of pages efficiently is not some fancy nice-to-have feature: it's absolutely fundamental.
From the roadmap, being able to scope search to manuals will be useful - as will be PDF downloads. Ideally it would be possible to download single-file HTML versions too.
It would also be useful to show back-references within the manual. Something like
https://www.lampfrey.net/adm/light/admP3.html#P3028
Assuming you're doing automated internal link checking, this should require little effort to implement.
Comment by Roo Reynolds posted on
Hi Tim.
> Do you have a time-table for moving DWP guidance (Advice for Decision Making and Decision Maker's Guide) to the new format?
Not yet.
> As a general principle, please don't turn off old resources until the functionality of the replacement is at least equivalent to that of the replaced. Being able to navigate a sequence of pages efficiently is not some fancy nice-to-have feature: it's absolutely fundamental.
I couldn't agree more. That's why we're taking exactly the approach Till outlines in this post. We won't be redirecting any HMRC manuals to the new versions on GOV.UK until we're confident that they're accurate and meeting the needs of users.
> From the roadmap, being able to scope search to manuals will be useful – as will be PDF downloads. Ideally it would be possible to download single-file HTML versions too.
We're working on search within manuals at the moment. That should hopefully come quite soon (along with better printing and previous/next links). Downloading an entire manual as PDF is one we're thinking about, but still trying to understand both the user needs and how we'd do it. If you've got an example of how it would help, I'd love to hear it.
>It would also be useful to show back-references within the manual. Something like https://www.lampfrey.net/adm/light/admP3.html#P3028
Ooh. Interesting. Thanks. We'll have to have a think about this. As with PDF, can you help me understand how it would help in the real world?
Thanks
Roo
Comment by Tim Blackwell posted on
Hi Roo,
Thanks for responding. On downloadable documents, the issue is really one of being able to take snapshots. Suppose .GOV.UK hosts the guidance on topic Z. We certainly want to be able to see the latest guidance, but we also want to be able to show that our past decisions on Z followed the guidance as it stood at the time. Downloadable PDFs, though dreadful in so many ways - I made the HTML version of the ADM above because I was sick of the drawbacks of its PDF counterpart, give us such a snapshot. That said, I would personally much prefer a government publishing format with significantly greater semantic power. Something like this:
-- Each document has a statement of purpose (what it's for) and an implementation part (how it's done). The statement of purpose never changes. The implementation part is amended as necessary. Whatever its presentation online, the document is downloadable as a single piece of HTML (conceptually and identifiably, if not literally) that includes the full modification history (and can show diffs), that is fully usable offline, and which when online can incorporate updates on user request.
On backlinks - obviously this is useful for editors - eg for checking mis-references (presumably the publishing system will check for obviously defective links). But it's also useful for readers. Suppose Paragraph X defines a particular UK residence status. If we can see everything that references paragraph X we can rapidly get a handle on its scope.
More generally, the value of information in government guidance is hugely dependent upon our ability to contextualise it. The more tools we have to help with that, the better.
Comment by Tim Blackwell posted on
An afterthought. I wonder whether it's worth experimenting with dividing the manuals into bigger chunks (perhaps you've tried this already). Small amounts of scrolling may be preferable to link following.
Comment by Tim Blackwell posted on
Oh just to add that if you do decide to cluster subsections (which I think would give a better browsing experience), please ensure each numbered section has an anchor so it can be linked to directly.
so
https://www.gov.uk/hmrc-internal-manuals/vat-government-and-public-bodies/vatgpb9320
would become
https://www.gov.uk/hmrc-internal-manuals/vat-government-and-public-bodies/vatgpb9300#9320
ps. Having hmrc in the URL is a good and useful thing.
Comment by Alan Rolfe posted on
Tim's suggestion of longer sections with anchors seems a good compromise and the "policy" of including the department, i.e. HMRC, in the URL would be a better way to mark content. May I suggest that it would be better still to use something like:
https://www.gov.uk/hmrc/internal-manuals/vat-government-and-public-bodies/vatgpb9300#9320
as this will allow external searches, etc. to restrict results to HMRC content by specifying site:gov.uk/hmrc/
Comment by Roo Reynolds posted on
Interesting idea. Thanks both. We'll have a think.
Comment by Kevin Ringer posted on
If you are proposing to use http://www.gov.uk/hmrc/.... then why not http://www.hmrc.gov.uk? How much energy and resources has gone into moving HMRC to GOV.UK only for us to have to waste hours trying to put everything back?
Comment by Ross Ferguson posted on
Could we have a post on this “write API” please? Sounds interesting and important.
Comment by Roo Reynolds posted on
Hi Ross. Good idea. Thanks.
Comment by Kevin Ringer posted on
Old layout and font is much preferable compared to new layout and font. Layout: old site had useful links along the top eg ‘tax agents and advisors’, new site does not have any useful links: it doesn’t even have a link to HMRC home page! Font: the old version fitted on one screen easily with space to spare, the new one fills my entire screen (24” monitor) and requires scrolling. Font is huge and “in your face”.
Comment by Kevin Ringer posted on
Navigation: old site had links Home/Main Contents/Manual Contents/Previous Page/Next Page/Top/Menu. New site has none of these. On the new site you have to go back to the contents, remember what numbered page you’ve left and select the next page. Ridiculous. Image it was a paper manual, it would be the equivalent of reading page 200 and instead of tuning over to page 201 having to go back to contents page 1, then 201, then 1, then 202. We need all the old links on the new site. One criticism of the old site was that the links were at the bottom of each page so it was always necessary to scroll to the bottom to link to the next page. Sometimes it was clear from the layout of the page that the user wanted to turn to the next page immediately, especially when going backwards. The solution was the have the links above and below the manual text. Can we have this on the new website please?
Comment by Roo Reynolds posted on
Thanks Kevin. We've recently added the previous/next links, though only to the bottom for now. I can imagine how having them at the top of the page too could help. We're currently working on making it possible to search within a the manual. We'll continue to work with HMRC on future improvements, including more work on navigation.
Thanks
Roo
Comment by Kevin Ringer posted on
Not every page has a next or previous eg the first page in a section does not have previous even though there is a previous page in the manual. Only the very first page in the manual should lack the link to previous page. Also there is still no Home, Main Contents, Manual Contents, Top or Menu.
Comment by Kevin Ringer posted on
We do need Next/Previous/Main/Home/Contents etc at top of page: but not in the massive font you've used at the bottom of the page because it will push the text further down the page. Already the GOV.UK layout means that when a new page loads the top 2/3 are taken up with the heading etc whereas on hmrc.gov.uk far more of the page is content.
Comment by Kevin Ringer posted on
Navigation: a suggestion. Could the window be divided into panes with the contents remaining visible in the left pane and the manual page in the right. Users could see where they were and rapidly move within each section
Comment by Kevin Ringer posted on
Search: how do users search within manuals? Text input into the search box lists results from across GOV.UK. It doesn’t even confine search to HMRC. I suggest there should be a list of departments on the left with ‘all departments’ ticked by default, users can then tick which departments they are interested in eg HMRC. Ticking HMRC should then open a range of tickboxes: Manuals, Notices, Leaflets, Forms etc. The user can then narrow down their target rage.
Comment by Stephen Edwards posted on
Kevin,
I was unsurprised by your comment "should then open a range of tickboxes: Manuals, Notices, Leaflets, Forms etc. The user can then narrow down their target range."
This was exactly what we were working towards when I wrote this blog post in March 2014:
https://hmrctransition.blog.gov.uk/2014/03/11/labelling-hmrc-document-types/
I even quickly hacked together a (very rough) static prototype for what this might look like:
http://hmrc-web.s3-website-eu-west-1.amazonaws.com/documents.html
This work was handed over to the GOV.UK specialist team and became known internally as "document sub-types". Unfortunately this was then abandoned and ruled out for the future by Neil Williams, who leads the GOV.UK product management. I no longer work on the project and I don't know the status of this work but I hope this decision is reconsidered. I could never understand why a decision was made to intentionally *never* try to meet a clear specialist user need. Using Document Collections is a terrible model to use for many reasons, not least the inconsistency in user experience and the artificial distinction between document types - reasons I alluded to in the blog post above.
Stephen
Comment by Kevin Ringer posted on
I attended a HMRC WT meeting where there was considerable negative feedback from agents and HMRC staff about GOV.UK. One key criticism is the size of the text. Why is it so large? I guess this is for mobile devices. If so, why doesn’t the website use normal size text for desktop devices? Most commercial websites (eg Amazon, eBay etc) resize their text for mobile devices. If GOV.UK is incapable of doing this, then I have a suggestion. Some websites have a tool allowing users to change the size of the text. I know I can reduce the size of my browser, but that reduces all sites and because all other sites display at the correct size it makes all other sites too small. So please GOV.UK either make the text smaller for desktops or introduce a setting for users. An example of such a setting are the 3 different sizes of A upper right of http://www.bbc.co.uk/accessibility/guides/.
Comment by Kevin Ringer posted on
Each line of text on the new website contains less characters than the old website. This makes the content taller requiring more scrolling. Why has each line been shortened on the new website?
Comment by Kevin Ringer posted on
Re length of line of text on new website: checkout https://www.gov.uk/hmrc-internal-manuals/vat-government-and-public-bodies/vatgpb6800 - the text is only 2/3 rds the length of the paragraph heading and banner. Surely it should all be the same length. Compare with the old website at http://www.hmrc.gov.uk/manuals/vatgpbmanual/VATGPB6800.htm where everything was the same width.
Comment by Mark Hurrell posted on
Hi Kevin, it's generally agreed that to maximise readability the optimal length for a line of paragraph text is between 50-75 characters per line. We usually try to follow that advice across GOV.UK, although we're actually setting the line lengths a little bit longer than that on the manuals (about 80 characters per line). Setting the text to be the same length as the headings would be a significant increase in line length and would have an equivalent effect on readability.
I agree that the alignments aren't perfect at the moment though. Like any page design on GOV.UK we'll be iterating it to make it better.
Comment by Kevin Ringer posted on
Mark, I'm a tax specialist that consults manuals several times a day. I have found that it is far easier to read the old manuals even though there are more characters per line. I have come to the conclusion that the larger text size on GOV.UK makes it harder to read blocks of text. The larger text size makes the page taller, requiring more scrolling. And the reduction in characters per line makes the page even taller again requiring more scrolling. It is definitely harder to take in text when it is so large. Compare this with a printed book. We have no difficulty reading tiny text in a paperback so why do we have to have such large text on GOV.UK? Please remember that manuals etc will mainly be accessed by specialists and not the general public so we don't need the presentation dumbing down.
Comment by Bryan Masterson posted on
I agree about the font size. It's very big indeed. The majority of users would prefer it smaller, and those who need it larger will know how to make it so or else not be able to use the rest of the web.
I also strongly dislike the forced page width. Unlike a book, users can resize their browser to whatever they like. However it doesn't matter if I have my browser at 2550px wide, you still force the text into a very narrow long column, and then make the font massive. right now the text fills less than 1/4 my screen width, a real waste of real estate.
I agree that you should present something everyone can use, however present something that the majority prefer and allow others to customise.
I have seen lots of feedback about font size, however it seems to be consistently ignored.
Comment by Ellis Pratt posted on
From what I can see, there's been two changes:
1. New look and feel
2. Changes to the navigation (and search)
The look and feel is fine, but the changes to the navigation are a significant step backwards. Kevin Ringer has highlighted the main issues with the navigation in his posts above.
I'm surprised the guides were published with those navigation elements stripped out. GDS has done great work on putting the reader first, but it seems in this case the technology has taken priority over the users.
Comment by Roo Reynolds posted on
HI Eliis
We knew this initial release was a very rough first pass. That's why the manual is still primarily on HMRC's old site and this experimental version is being worked on in public, to give a chance for this sort of feedback and for us to make it better. (Better to start simple and add more, I think, than re-create every aspect of the old site and miss a chance to come up with a better/simpler approach.)
If you take another look, we've just added previous/next links and are now working on making it possible to search within a manual.
We'll share more as we make more progress.
Thanks for your feedback
Roo
Comment by Stephen Edwards posted on
Hi Roo,
Thanks for adding the next/previous links. Two further improvements which would help immensely:
1) There are some dead ends. For example: https://www.gov.uk/hmrc-internal-manuals/vat-government-and-public-bodies/vatgpb1600
It isn't clear how you get to the next section of the manual without traversing back up the tree to a parent section and possibly missing a child page at the bottom. Being certain that you've seen 'everything' was a really important need that came out of user research with specialists.
2) Can you add next/previous links at the top of the page too? This definitely came out in the workshops and should be in the user stories you have, my error if not. On lower resolution screens (not uncommon for many corporate/professional users) the pages appear enormous and even then longer pages have to be scrolled through. Being able to click on next/previous at the top of the page negates the need to scroll and massively speeds up navigation. Some of the existing HMRC manuals have these in place, but it is inconsistent and (IIRC) was reliant on the author of the manual configuring this specifically in the Word template they used.
Keep up the good work, these are looking much better!
Stephen
Comment by Nick Taylor posted on
I've seen "point in time" functionality for other .gov.uk resources (e.g. Statutes), enabling the user to see the text as it stood for each update/rewrite.
Will this be made available for HMRC content at some point in the future?
I've seen one previous comment on this thread relating to looking at the guidance at a point in time that suggests inclusions of "downloadable PDF" of the manuals. Having something on the site itself (even a comparison tool to show "track changes" between versions) would be very useful to users.
If such functionality were to be enabled, would it be applied retrospectively? (i.e. to versions of the manuals pre-dating 2015...) And if so, how far back would you go?
Comment by Nick Taylor posted on
How "open" will the new HMRC content on .gov.uk be?
I'm interested in understanding if there is any accessible metadata and in what format (RDF, RDFA...), or what open APIs might exist to, say, index the content remotely without having to web crawl the full text.
I'm thinking of federated searching, or LOD mash-ups like openlaws.eu.
thanks,
Comment by Nick Taylor posted on
Are there any further updates (or blog posts I've been unable to find) that give further detail on roll out schedules/development roadmap for the HMRC content/publishing migration?
Working for a publisher that references and aggregates HMRC content it will be critical to understand when and how the content will move.
Comment by Graham Francis [GDS] posted on
Nick
Thanks for your questions.
We're expecting the move of HMRC manuals to the 'new', GOV.UK, templates to start soon - and will supply further details on the https://taxagents.blog.gov.uk blog, and in the HMRC Update to tax agents.
We understand the desire for downloadable PDFs of manuals - although we have no immediate plans to introduce this, it's something we'll look at doing in future.
Many thanks.