{"comment":{"url":"https://api.github.com/repos/R9BetterAPIs/documents/comments/9977941","html_url":"https://github.com/R9BetterAPIs/documents/commit/f9911f801f71f09979a03a2717c19ab94b53144a#commitcomment-9977941","id":9977941,"user":{"login":"gthurston","id":8562790,"avatar_url":"https://avatars.githubusercontent.com/u/8562790?v=3","gravatar_id":"","url":"https://api.github.com/users/gthurston","html_url":"https://github.com/gthurston","followers_url":"https://api.github.com/users/gthurston/followers","following_url":"https://api.github.com/users/gthurston/following{/other_user}","gists_url":"https://api.github.com/users/gthurston/gists{/gist_id}","starred_url":"https://api.github.com/users/gthurston/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gthurston/subscriptions","organizations_url":"https://api.github.com/users/gthurston/orgs","repos_url":"https://api.github.com/users/gthurston/repos","events_url":"https://api.github.com/users/gthurston/events{/privacy}","received_events_url":"https://api.github.com/users/gthurston/received_events","type":"User","site_admin":false},"position":1,"line":1,"path":"api.business.govt.nz/API website user research findings.md","commit_id":"f9911f801f71f09979a03a2717c19ab94b53144a","created_at":"2015-03-02T01:15:18Z","updated_at":"2015-03-02T01:15:18Z","body":"**Approach** \r\nPeople with an interest in the re- use or development of APIs were interviewed about a website that would be used for the exchange of information, data, analysis and dialogue about all things API.\r\nParticipants were sourced from agencies and the tech industry that represented a range of different roles i.e. developers, tech business owners, service owners, enterprise architects, e-consultants, business analysts and designers. \r\nParticipants were asked about:\r\n\r\n* Discovering the site - why they would use it\r\n* The value of the site – what sort of content would be useful\r\n* Engaging with the site – what would motivate them to engage\r\n* Returning to the site – what would make them re-visit the site\r\n\r\n**Key findings**\r\nNo one thought the website was a bad idea but how we do it is really important. Our words and actions will determine if it’s a success.\r\n\r\nLike the idea of a site that aggregates information about APIs that brings it all together in one place even if it links to content somewhere else. The goal would be to make it a relevant regularly updated ongoing reference point.\r\n\r\nDon’t underestimate the work required offline to make the website a success – use other engagement methods to drive people to the site. Work with people and invite them to comment.\r\n\r\nThe differences between agency and industry were not great. Both were mostly interested in the opportunity to find out more APIs in the context of opportunities for their business or how they can work better with colleagues from other agencies. Differentiating content for agency and industry is not appropriate.\r\n\r\n**1. Triggers for using or discovering the site**\r\n\r\n* An invitation from the team\r\n* Resource to refer back to after attending a conference/workshop/ personal engagement\r\n* Somewhere to direct a third party to somewhere after a meeting\r\n* Place to find an API\r\n* A link from somewhere else\r\n* A place to find business opportunities\r\n* A place to find out what my peers in government are doing. “I want visibility of what government is doing” “Help me join the dots to find common opportunities on how we could work together to solve a problem”\r\n\r\n**2a How to say it - engagement via the site**\r\nEngagement via the site is good idea but\r\nEnsure activity is followed up either with agencies and through responses on twitter and blogs. “We will use it if our perspectives are listened to and see suggestions followed” “there needs to be real commitment to do something”\r\nOther thoughts and comments about interacting with the site:\r\n\r\n* Be honest and open\r\n* “I’m sceptical of polls” - Context that they are a bit superficial\r\n* Ensure it links supply and demand. “Who can I partner with” “what do agencies have that’s valuable”\r\n* Use Loomio or github. Both help record a structured conversation about a subject. Twitter conversations can easily get lost over time. Suggested a FAQ to record recurring or common questions that come through on twitter or other communication channels etc.\r\n* I’ll only comment /interact if asked.\r\n* Generally just watch and see (Govt user)\r\n* Only if the topics were meaningful – “start from a position” e.g. put up a strawman to help elicit conversation.\r\n* Show comments / conversations\r\n* Make it easy for me to contribute\r\n\r\n* Explain how government people can contribute – tell them what the rules are as they are not sure how to comment\r\n* “Get me excited – make me want to contribute”\r\n* Structure the engagement “Show the things that need to be done that require support from people”\r\n\r\n**2b How to say it - using the site**\r\n\r\n* No government jargon and terminology\r\n* Industry participants saw government as all the same “I see government as all * the same entity and don’t care how it’s structured e.g. Result 9, 10, MBIE”. Regarding who promotes government APIs “I don’t care who in government does this, just as long someone does”\r\n* High level descriptions in plain English for content especially for education e.g. what is an API and how do they work?\r\n* Ensure its regularly updated.\r\n\r\n* Don’t re-create content\r\n* Link to what’s already available on the net to promote comment e.g. GCIO advice. Don’t re-badge other government content\r\n* Run site from github and allow others to request changes through that mechanism\r\n* Make it easy for me to find things\r\n\r\n* Don’t underestimate the work required offline to make the website a success – use other engagement methods to drive people to the site. Work with people and invite them to comment. Meet-ups could be an important way to promote work in a variety of different tech disciplines.\r\n\r\n* Make content available via google search. Make an API for the content.\r\n\r\n**3. What to say- suggestions for website content** \r\nWhat APIs are available or what APIs are coming in the future? \r\nThis was by far the most requested item that people want to see on the site regardless of their role and if they were in an agency or industry. It would fulfil needs of business to want to see what opportunities there might be for their products and agencies to find out what each other are doing and what data do they hold. The information people wanted see about the APIs included:\r\n\r\n* Who released them? i.e. which agency released them.\r\n* What services do the APIs support?\r\n* How are the APIs used and by who. Industry people wanted to know so they can create a community of practice around that API. Agency people want to know to find out who the players are in the market to find out more about what they want in order to assess future opportunities to work with them.\r\n* Contact details of people responsible for the API\r\n* SLA and T&C for specific APIs\r\n* Dashboard of API statuses e.g. what fixes is required?\r\n* Developers wanted technical details e.g. boundaries and endpoints, data formats, sample code.\r\n* Timeframes for future APIs. “what’s coming, what’s being delivered soon, what’s been released and what’s been the uptake”\r\n\r\nAPI education\r\n* Included: API definition, How they work and why do they matter? How to get one and use one.\r\n\r\nCase studies that show examples of use\r\n* NZ and international examples for open data and transactional APIs. Case studies from different perspectives e.g. agency, industry, how did they do it.\r\n\r\nResources \r\n* Essentially the things requested here were API building blocks and were technical in nature. These included:\r\n\r\n  * Sample documentation\r\n  * Sample SLAs and T&C\r\n  * Design guidance e.g. technical design and service design\r\n  * Standards for API good practice\r\n\r\nIndustry was particularly interested in how NZ government is going to build these APIs in a consistent way that allows easy integration. Agencies were also interested in these as it fulfils a need to “speak the same language”. Areas of interest for standards included:\r\n\r\n  * Authentication and access\r\n  * SOAP vs REST argument\r\n  * Security\r\n  * Privacy\r\n  * Testing\r\n  * Use of open source approach\r\n\r\nBlog / engagement opportunities \r\n* Ensure there is a place to show and record conversations about the content.\r\n\r\n**Content that people indicated would be useful in the future and would make them want to re-visit the site**\r\n* More content about the subjects of interest (see above)\r\n* More APIs\r\n* News of latest developments\r\n* Updates on conversations e.g. twitter and blog comments\r\n* Workshops and training"}}