🥁First strategy #webinar of the year: 31 January❗ Join @kvantomme to learn about how to build your #strategy for c… https://t.co/pTIjAapD7s
Developer advocate at Nexmo
API documentation is key, but "sometimes developers and documentation just don’t mix." Developer eXperience is giving developers what they need to succeed, and OpenAPI specification (OAS) can help in that.
OAS
Is a good choice for describing RESTful APIs in a machine readable-way,
Enhances DX: an API spec is reusable and this can be super powerful,
Is a result of teamwork: product owners, writers, engineers should co-write it.
New APIs or existing ones?
Retrofitting an existing API into OAS is not always easy, but it’s doable and valuable,
Spec-first API design: cheaper and effective way to design a new API starting on actual development, with all the stakeholders included in the conversation (product owner, writer, engineer).
Anatomy of OAS
Tree structure, like a ToC with chapter headings, subheadings,
Json or yaml file holds the description,
Add (standardized) metadata now for discoverability in a future API ecosystem ,
Lots of APIs? Group and re-group using your tagging system.
Tools
ReDoc: render the yaml to your branding, the front-end is entirely separate from the spec content,
Source control! Commit the description file when it's working,
See further Lorna Jane's presentation on editing-, validation- and preview tools.
"The initial discussion to design a new API, even before starting developing it, is a very cheap stage of the process and can save lots of costly pains later if you include all the stakeholders in the conversation" -- #apithedocs London is @medjawii talking about APIs in banking and their developer portals pic.twitter.com/46d0DBiBkE
— Eva Casado de Amezua (@1KHats) November 9, 2018
Technical writer at Shopify
The relationship of the resources may be complex. Organizational and product marketing considerations will dictate the content (mental models).
Casing conventions are necessary for comprehensive navigation.
Depending on your APIs, may group by area of functionality or by product marketing technology.
A devportal's content is not just transactional, it is relational. "Inconsistency in your documentation patterns slowly erodes your developers' trust, even if they don't tell you."
Style guides
Writing without a style guide can cause inconsistency which can lead to losing the developers’ trust,
A model is needed, especially if your team starts to grow, and there are more writers with different levels of experience.
Style guide playbook
Research on best practices and decide on your own house style
Examples style guides:
Publish
The software developer’s job is to ensure the API is working.
The developer evangelist and product marketer are to sell the API.
The technical writer has to ensure that the APIs are documented efficiently and consistently.
Andrew Johnston @andrewjtech is talking “The Trials and Tribulations of the API Style Guide”#APITheDocs #devrel #devreljp pic.twitter.com/FgQ6zyYczY
— Taiji / Speaker@JJUG CCC 2018 Fall (@taiponrock) November 9, 2018
API Strategist at Axway
The likelihood of a purchase drops sharply as the number of decision makers increases
Devportals spectrum options — to buy (might not meet all the requirements, implementation is needed) or to build (starting from scratch, choosing stack, allocating resources),
Consider the competition and understand the business landscape.
Content strategy — solutions
Long-tail keywords: engineering/developer-focused results,
Engagement with the dev community: publishing and maintaining relevant content is key,
Long-term strategy: engagement is far deeper than a financial transaction, it’s relational.
Software architecture — solutions
Design-first approach is less expensive,
Provide a safe place to share information, — Slack is moderated, has community guidelines and people can discuss questions with experts (professional developers),
Continuity of care (it is quite possible that a devportal content strategy is more about service),
Test DevPortal interaction — physical prototypes foster conversations about how we interact,
Measure impact: customer and developer journey mapping.
API maturity and resources define the content lifecycle: no portal or pre-devportal (API references only) → rebuild devportal (relaunch) → optimize devportal
Takeaways:
The API specification should be the core of your API content strategy,
Provide business context (through strategic partnerships) and technology context (speed, performance),
Map out where traffic is coming from and where it goes. Crosslink between the two where it makes sense,
Ask developers what they want and stay true to deliver what they tell you,
Your content strategy needs to match your business and is a direct reflection of your relationship with your developers,
Content strategy for DevPortals is all about delivering a high value experience to win and to keep customers,
Measure impact,
One of the ways to achieve high value experience is through the highest quality DX with high availability, digital experience, security and business intelligence,
Don’t just offer giveaways, let the quality of the content and engagement drive the value,
Goal of a great devportal: make it evolve from “a devportal” to “my developer portal”,
The best way to recognize your developer community is to invest in them over time.
The path of being a technical communications strategist is full of different skills learning (check that slide!)
— Eva Casado de Amezua (@1KHats) November 9, 2018
-- @lifewingmate #APITheDocs pic.twitter.com/Cozpt0lwYd
Business Analyst at HM Revenue & Customs
Technical Writer at HM Revenue & Customs
Tony and Mick started their presentation with demoing their Developer Hub — home page, getting started, general documentation examples, API docs list, API docs example.
How they write?
Writing style — finding a common language,
Following style-guides (GOV.UK, HMRC and Developer Hub),
Ideally pair-writing — less efficient with asynchronous collab tools (GDocs),
Choosing RAML over Swagger and JSON schema,
Convert RAML to HTML,
Consistency across different teams.
Feedback and iteration
End to end doc needs — beyond the API
Their approach to API development: design, delivery, governance, HMRC’s API Service Process and Standard, GDS (currently only internal) API design best practices.
Takeaways:
Feedback and user research are essential,
Documentation quality actually matters — it can make a difference to API consumers,
Developers' experience, standards, programming language, thinking style etc is on a wide spectrum,
A complex API needs extensive contextual documentation — end-to-end user journey,
Ease and speed of doc updates matter — need a lightweight CMS (docs-as-code), GitHub, markdown processor.
Mick and @tonyheapuk flying the flag for gov docs and their ace work on HMRC Developer Hub #APITheDocs https://t.co/O3Yu5ZfoKO
— Jen Lambourne (@Jenny__Anne) November 9, 2018
Head of API Euler Hermes at Euler Hermes
Why we need more than only great DX: discovering the devportal fast then going into development is not the whole story.
Key requirement: non-technical demo of the API’s business value
A large number of people are involved in the entire process with different needs and experiences:
Key business needs/requirements
Non-technical demonstration of the API’s business value,
Functional API catalog,
Inspirational use cases beyond the API,
Exact API solution suggestions to enhance a certain process within the business user interface,
Easy communication channel,
Support for estimation of project efforts and business case calculation,
Second level support — clearly defined contracts.
Key needs/requirements of developers
Tutorials: easy introduction to the business context,
Detailed explanation of key legal requirements,
Highlight business consequences of functional errors,
Clear link between API docs and related functional use cases to make IT and business really together in this.
The BizDevPortal’s characteristics:
Has a mixed team of business and IT experts,
Enhances end-to-end UX,
Complies with legal requirements,
Is backed by professional support when needed.
Takeaways:
"Thinking that a Dev Portal only has to take care of getting the DX right is not enough. The business people need to understand the functional value of the APIs as well."
— Eva Casado de Amezua (@1KHats) November 9, 2018
-- Sophie Rutard, @eulerhermes#APITheDocs pic.twitter.com/c2lDief3VJ
Chief Architect at Capgemini UK
APIs are doors to information and functionality. They’re an organisation’s main entrance to digital services and offerings.
What can help?
API design-first approach with continuous testing and feedback,
Microservices are APIs,
Strong emphasis on domain-driven design.
Why Apiary?
Benefits of API-design first
Avoid rework by implementing feedback-loop in the earliest phase of the API lifecycle,
Parallel development: decouple App dev from Service dev,
Up-to-date API documentation.
Great collection of links here from @Luisw19 for #dredd #apiary and more from #APITheDocs pic.twitter.com/QnmYbCM0aP
— andrew johnston (@andrewjtech) November 9, 2018
Product Manager at VMware
The Evolution of VMware APIs
Richard’s presentation included a demo of the VMware’s API explorer, which is
Customers’ reaction: the API explorer felt like much more an entire developer microportal.
Streamlining Content Management: DxPress
What’s next? VMware {code} 2.0
How to achieve it
How to deal with a situation of high technical-product complexity?: Streamline into a Dev Center Framework (Developer Portal as a Service) @rthomchick#APItheDocs pic.twitter.com/sn5hCLSIfC
— Eva Casado de Amezua (@1KHats) November 9, 2018
Technical Writer at Moogsoft
What is the problem?
Beware:
What is GraphQL?
Key principle: thinking in graphs, where a graph is like a tree.
Advice from the co-creator Lee Byron
GraphQL Voyager: explore your API as if it was an interactive graph and the schema, how things relate to each other.
What is the answer?
GraphQL can be self-documenting as in self-explanatory: providing you spaces to fill.
@jwscott22 totally nails it in his #APItheDocs talk about how he researched and debunked the “self-documenting” myth for GraphQL and explains why technical writers have a key role to play documenting it. pic.twitter.com/KhUzkhXENA
— Emmelyn Wang (@lifewingmate) November 10, 2018
Lead API Writer at Worldpay
Brief introduction to Hypermedia
How is it different from REST?
Why a hypermedia API?
Documentation
The resource tree maps out how each resource can be reached. For each resource its own json file, this gives more space for adding examples.
Where next?
Takeaways
HATEOAS is not for everyone (at least at this point), but it can have value in specific use cases @NickJBradley #APItheDocs pic.twitter.com/G6W12TqE14
— Kristof Van Tomme (@kvantomme) November 9, 2018
CEO at Moongift
Localization
GitHub Wiki
Localization with GitHub Wiki
Documenting in code with comments
Atsushi’s workflow
Learning #API with Manga!! A new one for me !! Interesting talk on the multi-lang API docs. @APItheDocs #APITheDocs conclusion: Translating <> Localisation pic.twitter.com/9A7ndh1twa
— Luis Augusto Weir (@Luisw19) November 9, 2018
Developer Evangelist at Postman
Types of APIs
Postman 2018 API Survey
Three steps in the developer journey
Building awareness for (Public APIs)
Building awareness (Private APIs)
Gaining API adoption (both Private and Public APIs)
Maintaining up-to-date and accurate documentation (both Private and Public APIs)
Takeaways
Docs are part of the API. Make sure they are included in the definition of done. @PetuniaGray #apithedocs pic.twitter.com/5OFKmBzfQw
— Alberto Perdomo (@albertoperdomo) November 9, 2018
Developer Advocate at Box
Cristiano held a live API experience review, started his session with looking for candidates who meet the criteria:
The goal of his review session was to find out how the onboarding works and how easy it is to get started.
During the demo he created a friction log, where he added examples of pleasure, frustration and pain he experienced, extended it with his suggestions.
He reviewed PipeDrive’s APIs from these aspects:
How easy is, really, to onboard your API? Write a friction log about your product, and find out.
— Eva Casado de Amezua (@1KHats) November 9, 2018
-- @cbetta about to test the developer experience of APIs among the public#APItheDocs pic.twitter.com/ogWyaKHRss
Original recording of the conference by Kristof Van Tomme, Creative Commons Attribution Share-Alike License v3.0
🥁First strategy #webinar of the year: 31 January❗ Join @kvantomme to learn about how to build your #strategy for c… https://t.co/pTIjAapD7s
We're excited to bring you the new virtual sessions of #APItheDocs focusing on the importance of #feedback #metrics… https://t.co/ifmptrM2bk
The #APItheDocs Virtual series returns in January, focusing on what is worth measuring on the community side of do… https://t.co/hS5D5ZzGg0
💡What are the essential elements of #developerportals? 💡How do you build a strategy that creates and catalyzes grea… https://t.co/5xstaoMV2w