The HMRC Developer Hub provides documentation for HMRC APIs and has learned several lessons from its experience. It has found that (1) feedback from developers is essential, as they come in various levels of experience; (2) documentation quality greatly impacts developers' experience with APIs; and (3) documentation must be easy to update so it remains helpful. Continuous feedback has helped the Hub improve its documentation and services for developers.

1. HMRC Developer Hub:
an Experience Report
What have we learned?
Tony Heap - Business Analyst
Mick Schonhut - Technical Writer
HMRC API Platform team

2. HMRC Digital
HMRC Developer Hub
● Helps developers integrate their software with HMRC APIs
eg. software to submit tax returns or customs declarations
● In beta for 2.5 years - went live in Sept 2018
● 52 APIs so far and still growing (many are private or in private trial)
● 1.1 to 1.2 million API calls per day with 99.99% availability
● Grown steadily to 20+ teams in HMRC producing APIs
● Over 200+ external API consumers, including:

3. HMRC Digital
Demo
https://developer.service.hmrc.gov.uk/api-documentation
● Developer Hub homepage
○ General documentation examples:
■ Using the Developer Hub
■ Authorisation
○ API documentation list
○ API documentation example:
■ Individual Employments
● Intro sections
● Endpoint details

4. HMRC Digital
How we write documentation
● Writing style - finding a common (ubiquitous) language
○ Eg “company benefits” or “employment benefits”?
○ GOV.UK, HMRC and Developer Hub style guides
● Content
○ Pairing is really important - a Subject Matter Expert (Tony) and writer
(Mick)
○ Ideally done in real time - can be done asynchronously with
collaboration tools (Google Docs) but less efficient

5. HMRC Digital
Our experience with RESTful API
Modelling Language (RAML)
● Chose RAML over Swagger (now OpenAPI)
○ Betamax versus VHS :)
● We use RAML v1.0 and JSON Schema
● API producer teams create a RAML file to define each version of their API
● Convert RAML to HTML - a single API documentation page with standard
sections and API endpoint details
● Gives consistency of API documentation across different teams - but are
still challenges from different API content needs
● Some limitations in content types rendered eg diagrams

6. HMRC Digital
Feedback and iteration
● How we get feedback
○ 30+ cycles of user research testing in beta
○ Sign out survey
○ Beta banner feedback (until recently)
○ Feedback tool - heatmaps, pop up polls and a survey
● How we iterate the documentation
○ Compile individual feedback tickets into specific page “quick wins”
○ Share API doc feedback with API producer teams

7. HMRC Digital
End to end documentation needs -
beyond the API
Development audiences including entrepreneurs, product owners, business
analysts, architects, lead developers have extra content needs:
● Timelines for staged API development and rollouts (“Roadmap”)
● Usage scenarios and relationships between related APIs and endpoints
● End to end user journey contextual information - about sole traders, limited
companies, non-profits, agents, agencies, etc.

8. HMRC Digital
Prototypes:
● API documentation groupings
https://hmrc-devhub-cycle-31.herokuapp.com/api-docs-migrate/api-docs-f
ilter
● VAT Roadmap (GDS tech doc template)
https://hmrc-vat-roadmap-cycle-33.herokuapp.com/#vat-mtd-roadmap
● VAT End-to-End Service Guide (GDS tech doc template)
https://hmrc-vat-e-to-e-wd-cycle-33.herokuapp.com/#vat-mtd-end-to-end-
service-guide

9. HMRC Digital
Our approach to API development
● Design
● Delivery
● Governance
● HMRC’s API Service Process and Standard
https://confluence.tools.tax.service.gov.uk/display/DP/API+Service+Process
● We've been helping Government Digital Service (GDS) to draft cross
government standards for API docs
https://www.gov.uk/guidance/gds-api-technical-and-data-standards

10. HMRC Digital
What have we learned?

11. HMRC Digital
Feedback is essential
● User research is just as important as for public facing services - developers
come in all shapes and sizes!
● Sign out surveys and beta banner surveys - just get ignored
● In-page polls are powerful - but can irritate users
● Analytics (page popularity) have helped a bit
● Heatmaps have helped a bit
● Feedback from API producers - from API hackathons - very useful
● Produce our own APIs to “eat our own dog food” - and run our own
hackathons - very useful

12. HMRC Digital
Documentation quality really matters
● Getting quality across API documentation is hard
● API producer teams don’t normally hire technical writers
● API developers often left struggling to produce documentation
● API developers tend to prioritise API build over docs (it’s an Agile value!)
● API producer teams sometimes don’t even do user research
- “We’re an API - we don’t do user research”
● Good quality documentation really makes a difference to API consumers (and
poor quality documentation is really a problem)

13. HMRC Digital
Developers come in all shapes and
sizes
● API platforms are hard to explain simply (e.g. OAuth 2.0 standard)
● Not all developers are as experienced as you might think
● Everyone wants examples and code snippets - in their favourite programming
languages
● Some people are very visual thinkers - can't or won't read the text between
the code snippets
● Complex APIs need a lot of contextual documentation - about the end-to-end
user journey

14. HMRC Digital
Ease and speed of doc updates matters
● We need a lightweight CMS so we can make changes more quickly & easily -
“Docs as code” model
− We're building one based on GitHub and a simple markdown processor

15. HMRC Digital
Headlines - what we have learned
● Feedback is essential - just as much as any public facing service
● Documentation quality really matters to developers
● Developers come in all shapes and sizes
● Ease and speed of documentation updates is really important

16. HMRC Digital
Questions?
For Tony (the BA) or Mick (the writer) or the both of us…
Email: tony.heap@digital.hmrc.gov.uk
mick.schonhut@digital.hmrc.gov.uk
Read our latest blog post at:
https://hmrcdigital.blog.gov.uk/2018/10/18/the-developer-hub-is-live/