WTSB 19th June 2018 - adopting GDS and thinking about documentation
We held the second meeting of the Welsh Technical Standards Board (WTSB) today and I am delighted to announce that we have formally adopted the GDS Design Principles for use by NHS Wales. These are:
- Start with user needs
- Do less
- Design with data
- Do the hard work to make it simple
- Iterate. Then iterate again
- This is for everyone
- Understand context
- Build digital services, not websites
- Be consistent, not uniform
- Make things open: it makes things better
In addition, we have agreed to adopt the Welsh Government Digital Service Standard:
- Undertake research of who the service users are, to understand user needs.
- Have a plan in place for ongoing user research and usability testing.
- Have a multidisciplinary team.
- Build your service using agile iterative and user-centred methods.
- Build a service that can be iterated and improved on a frequent basis and make sure you have the capacity, resources and technical flexibility to do so.
- Evaluate what tools and systems will be used to build, host, operate and measure the service, and how to procure them.
- Understand security and privacy issues.
- Consider making source code open and reusable, and, if appropriate, publish it under relevant licenses.
- Use open standards and common platforms where available.
- Test the end-to-end service.
- Make a plan for being offline.
- Create a service that’s simple and intuitive that users succeed first time.
- Make the user experience consistent with the rest of Welsh Government.
- Encourage everyone to use the digital service with assisted digital support if required.
- Identify your baseline information to measure performance
- Collect that performance information regularly
- Report on that performance data.
- Test your service from beginning to end [with your minister]
Implicit in adopting these standards is a focus on the citizen as the user of services and that digital transformation is better thought of as service transformation. We need to provide tools so that our services can be transformed to provide modern, efficient and safe healthcare.
To that end, we are starting a transformation journey, with collaboration, cooperation and openness the key enablers for us to make things better. In essence, we need to balance top-down standards with creating a culture of openness and transparency to enable safe innovation.
Our remit, as a board, is to define the technical principles and standards supporting:
- software development
We are accountable to the National Informatics Management Board (NIMB).
Making things better for users
Not only should NHS Wales work to GDS principles, but we as a board should too. To that end, we must ask
As a technical standards board, who are our users?
I see developers, together with the teams in which they work, as the prime user for our technical standards because they are the ones who will make things better for the real users, patients and professionals.
And what do developers need? Can we apply the GDS principles in our task to maintain a catalogue of principles and standards?
In essence, our standards will specify the structure and function of our national architecture and documentation of those standards should, if we take an open-approach, foster a change in culture towards collaboration and cooperation and trust.
We will, in essence, define the specifications for an open platform onto which we can build innovation and enable true service transformation.
So what next?
There are some logical consequences to this approach:
- We must open up our documentation relating to services and their standards and develop a roadmap to assess and set new standards and decommission old ones.
- We must move to creating cross-functional teams that combine developers, project management, user researchers, UX designers with testing, safety and deployment experts to deliver modular, domain-constrained functionality that can be developed and improved in isolation to other components. Such components should, in essence, be loosely-coupling with technical and human contracts defining interactions between teams. For Wales, we should encourage teams that combine members that span organisational boundaries
- A focus on automated end-to-end testing and scalability with testing in production-like environments available on-demand.
For the rest of this post, I want to talk about documentation as it is a key enabler for building collaboration, cooperation and trust in Wales.
What do other developer-focused digital companies do when they want to create an open platform? They create a developer-friendly set of documentation with application programming interface (API) specifications together with how-to and getting started guides.
Imagine you are a developer wishing to build software using the NHS Wales open platform. You might work for the NHS Wales Informatics Service (NWIS), one of the health boards or a commercial or academic partner What do you need to get your work done?
Let’s look at how others have done this…
This is the current landing page of https://docs.microsoft.com
Here there are links to documentation covering the range of Microsoft platforms, including Azure, their cloud platform. Let’s explore…
We can read broad overviews of the architecture, and see links to more detailed specifications in the API reference:
Similarly, the documentation is interspersed with example code and links to frameworks that make it easy to make use of the software services provided by the platform.
But how do Microsoft keep their work updated? The source code for their documentation is either automatically generated from their code, or maintained itself as an open-source repository on github - see https://github.com/MicrosoftDocs:
This fosters collaboration. Internal users can contribute to changes and have them accepted by the project team, but so can external users. I could make my own local copy of this document repository, make my changes and submit them for review as a “pull-request”.
We can edit the original source to the documentation, here in Markdown format, a simple-to-use and process text markup language. Microsoft maintains control of the source, but permits open access and review and collaboration. Have a look at https://github.com/MicrosoftDocs/azure-docs
And from these source files, Microsoft generate their website:
Amazon Web Services (AWS) have adopted the same approach:
Here we have their landing page, linking to lots of different resources, including guides, lists of API specifications etc. And here are the github pages containing the source for those documents.
And in the same way as for Microsoft, developers can flag omissions or errors and contribute. This user is submitting a patch to add a link to another resource. Other users might simply create an “issue” to be examined and possibly fixed by the project team.
So today we agreed that, in line with our remit, we must start work on building an online catalogue of existing services and the standards that are used, and, by adopting GDS-principles ourselves, do this in the open and in small incremental steps. As such, we are going to pick a current service and see how we can take some tentative first steps in publishing that documentation as well as making use of tools to support cooperation and collaboration.
If you have any comments or thoughts, let me know. I promise to tell you how we get on, and share the learning, the results (good or bad) with you.