Skip to main content

Content clinic 27 November: what we talked about

Posted by: and , Posted on: - Categories: Best practice, Events

Content editors came together at the Home Office last week to share knowledge, ask questions and discuss common themes.  Here’s what we talked about.

GDS updates

Mainstream content designer John Turnbull talked about how to write Zendesk tickets. He’s shared his notes in Basecamp.

We’ve noticed a tendency to use document collections as a landing page. Ben Clancy talked about how to make better collections of documents grouped around one task or theme. We recently updated our guidance on document collections - see the content design manual to find out more.

We showed how to download lists of documents from Whitehall, and talked about the next round of spot checks, which we’ll send out this week.

Questions we covered


We were asked how manuals work in practice and if special permissions are needed to publish them. Manuals are created using a tool called specialist publisher, which you’ll need permission to use.

Manuals can’t currently be printed or added to a document collection, but you can put a text link into your document collection if needed.  They can now be tagged to a sub-topic. To request a manual, follow the approvals process in the support for government publishers manual.


We received a few questions on when to use HTML or PDF attachments. HTML is better for SEO and for small screens, but there’s no reason you shouldn’t use a PDF if that’s what users want. Use Feedback Explorer to find out what users are saying about your content, and check use by device. Where there is a clear user need you may want to use both formats, but bear in mind you’ll need to keep updating both.

Inline attachments

One editor asked why we advise against using inline attachments in detailed guides. We said use your judgment, but if you want to use text links to documents it’s better to create them as separate publications first. They’ll show up in search, and you’ll be able to see user comments and get analytics on the page.

Questions we didn’t get to on the day

How do we get analytics for PDF downloads?

Currently we can’t give you stats for PDF downloads in Google Analytics. We’re frequently asked this, and it’s on our to-do list for 2015.

How many documents should you have on a single publication?

There’s no hard and fast rule, but in general documents should only relate to 1 user need.  So include whatever it is the user needs to know to do that thing. Don’t create separate publications if it’s not necessary, and put translations on the same page. You’re meeting the same user need, just in a different language.

However, if you find you’re adding more than 3 or 4, stop and think about it. You may be trying to meet too many user needs with that 1 publication.

How do people read longer documents online?

GDS trainer Christine Cawthorne recently blogged about creating a better user experience, which includes links to some research about how people read online.  We hope this helps.

Thank you to everyone who came along or submitted questions. Special thanks to Home Office for hosting at short notice.

Sharing and comments

Share this page