Increasing API Adoption via a Code Playground
•Download as PPTX, PDF•
1 like•2,307 views
This session will elucidate what is an API Code PlayGround, and how does it create a phenomenal developer experience. We'll be focusing the two main components of the Code PlayGround: SDKs and Reactive Code Samples. Developers love SDKs — simply because SDKs lift heavy burden of communicating with an API, and let developers focus on the app design and business logic. On the other hand, Code Samples provide the quickest way to the first “Hello World” application. Combine both as a Code PlayGround, and you’ll get developers up and running with your API within no time.
Report
Share
Report
Share
Recommended
By the time they're reading the docs, it's already too late
Your relationship with a developer begins before they even know your product's name. In fact, before they know they need a product like yours.
In this talk, Matthew will make the case that developer marketing, developer experience, and developer education are part of a continuum. And that if you're thinking of documentation as something that happens only after someone has signed-up for your API, then you're leaving it too late. He'll draw on pedagogical and marketing research to propose a model for the developer learning journey where traditional API documentation is just one stop along the way.
Attend this talk and you'll come away with practical ideas for how to start educating developers earlier in their product evaluation and learning journey.
Optimizing Dev Portals with Analytics and Feedback
Making informed decisions on which features to prioritize in a developer portal can be a daunting task. In this session, we'll show you how to leverage experiments, data, and user feedback to evaluate their potential and refine your approach. We'll explore how testing ideas with minimal investment, akin to an MVP, can help you avoid building features that don't meet your users' needs.
Success metrics when launching your first developer portal
Building our a developer portal may seem easy at the onset with off the shelf options, but when you're building a custom portal to match the needs of your company, it's not as easy. In this session, we'll talk about our process in determining the right places to start with success metrics and features through an early stage feedback back before having customers. You'll see our intention is to tell a story with multiple facets for multiple people, developers, product managers, C suite decision makers etc... Stories around API usage, health, cost, errors and support to provide our users with an overall of their business performance through our APIs.
Documentation, APIs & AI
AI is entering the world of APIs, where API documentation plays a critical role. One of the fundamental challenges is the need to share understanding about an API and keep the knowledge up to date. AI can potentially speed up API integrations dramatically, but it greatly depends on API documentation.
Let's explore the emerging approach to employing AI in APIs, discuss its impact on API documentation, and see how changing our way of working with APIs will lead to self-integrating applications.
Making sense of analytics for documentation pages
As content producers, we invest considerable time and effort in developing, packaging, and delivering content that we think our users need. After publishing the content, we hope that users find our content useful. And we often wonder how users really navigate and consume our content. Web page analytics can help us gauge the information needs of our customers, assess their content consumption behavior, and find opportunities to improve our content and how we deliver it.
Kumar explores the basics of web analytics, pitfalls of relying too much on web analytics for important decisions, the typical web analytics process, and he will share some guidelines for interpreting web analytics numbers.
Feedback cycles and their role in improving overall developer experiences
Drawing from experiences from open source work and her time at Spotify, Serah’s talk cover the challenges, opportunities and hacks around proactive and reactive monitoring, processing, tracking and acting on stakeholder and community feedback, and argue for the centricity of well-defined feedback loops in improving the overall developer experiences for any product and features you are responsible for.
GraphQL Isn't An Excuse To Stop Writing Docs
The main goal of API documentation is to help developers understand how to use an API. With GraphQL, developers often assume it's self-documenting capabilities are sufficient for anyone that consumes their GraphQL API. But did you ever validate this?
Good API documentation offers both static and interactive ways to learn how to consume the API. API's that support GraphQL often only come with interactive documentation, in the shape of a GraphiQL Playground. However, the first time you (or your users) use a GraphQL API can be very frustrating as GraphQL APIs typically only have an interactive playground. it increases the complexity for newcomers to GraphQL as it assumes you’re already familiar with GraphQL. But with GraphQL, you’re not limited to just an interactive playground, as you can create static or interactive documentation next to having this playground. This talk explores which forms of documentation you can use and how they add value to your GraphQL API.
API Documentation For Web3
Web3 is one of the fastest-growing spaces on the web right now, with thousands of new projects emerging every week. Each project aims to fill a gap in the space by providing a new technology How do we keep up with documentation, and what should be prioritized for these projects as they scale?
Web3, also referred to as the read-write-own web, is a new form of the internet that utilizes technologies such as blockchain networks, cryptocurrency, crypto wallets, and digital assets like NFTs. The Web3 space is growing by the thousands every week, with new projects and technologies constantly emerging. As writers, it can be challenging to navigate through the space, make sense of every piece of new content, and understand what should be written about for others to read, and what will be irrelevant next week. Many of these new technologies are using pieces of code known as smart contracts or interacting with the APIs of multiple applications at once. What documentation are end-users looking for, and what is the most beneficial format for them to read and comprehend all of this new information? In this talk, I'll discuss what I've learned as a Senior Technical Writer for Filebase, a decentralized cloud storage provider at the heart of hundreds of Web3 projects, and what our customers have benefited from the most when it comes to documentation.
Recommended
By the time they're reading the docs, it's already too late
Your relationship with a developer begins before they even know your product's name. In fact, before they know they need a product like yours.
In this talk, Matthew will make the case that developer marketing, developer experience, and developer education are part of a continuum. And that if you're thinking of documentation as something that happens only after someone has signed-up for your API, then you're leaving it too late. He'll draw on pedagogical and marketing research to propose a model for the developer learning journey where traditional API documentation is just one stop along the way.
Attend this talk and you'll come away with practical ideas for how to start educating developers earlier in their product evaluation and learning journey.
Optimizing Dev Portals with Analytics and Feedback
Making informed decisions on which features to prioritize in a developer portal can be a daunting task. In this session, we'll show you how to leverage experiments, data, and user feedback to evaluate their potential and refine your approach. We'll explore how testing ideas with minimal investment, akin to an MVP, can help you avoid building features that don't meet your users' needs.
Success metrics when launching your first developer portal
Building our a developer portal may seem easy at the onset with off the shelf options, but when you're building a custom portal to match the needs of your company, it's not as easy. In this session, we'll talk about our process in determining the right places to start with success metrics and features through an early stage feedback back before having customers. You'll see our intention is to tell a story with multiple facets for multiple people, developers, product managers, C suite decision makers etc... Stories around API usage, health, cost, errors and support to provide our users with an overall of their business performance through our APIs.
Documentation, APIs & AI
AI is entering the world of APIs, where API documentation plays a critical role. One of the fundamental challenges is the need to share understanding about an API and keep the knowledge up to date. AI can potentially speed up API integrations dramatically, but it greatly depends on API documentation.
Let's explore the emerging approach to employing AI in APIs, discuss its impact on API documentation, and see how changing our way of working with APIs will lead to self-integrating applications.
Making sense of analytics for documentation pages
As content producers, we invest considerable time and effort in developing, packaging, and delivering content that we think our users need. After publishing the content, we hope that users find our content useful. And we often wonder how users really navigate and consume our content. Web page analytics can help us gauge the information needs of our customers, assess their content consumption behavior, and find opportunities to improve our content and how we deliver it.
Kumar explores the basics of web analytics, pitfalls of relying too much on web analytics for important decisions, the typical web analytics process, and he will share some guidelines for interpreting web analytics numbers.
Feedback cycles and their role in improving overall developer experiences
Drawing from experiences from open source work and her time at Spotify, Serah’s talk cover the challenges, opportunities and hacks around proactive and reactive monitoring, processing, tracking and acting on stakeholder and community feedback, and argue for the centricity of well-defined feedback loops in improving the overall developer experiences for any product and features you are responsible for.
GraphQL Isn't An Excuse To Stop Writing Docs
The main goal of API documentation is to help developers understand how to use an API. With GraphQL, developers often assume it's self-documenting capabilities are sufficient for anyone that consumes their GraphQL API. But did you ever validate this?
Good API documentation offers both static and interactive ways to learn how to consume the API. API's that support GraphQL often only come with interactive documentation, in the shape of a GraphiQL Playground. However, the first time you (or your users) use a GraphQL API can be very frustrating as GraphQL APIs typically only have an interactive playground. it increases the complexity for newcomers to GraphQL as it assumes you’re already familiar with GraphQL. But with GraphQL, you’re not limited to just an interactive playground, as you can create static or interactive documentation next to having this playground. This talk explores which forms of documentation you can use and how they add value to your GraphQL API.
API Documentation For Web3
Web3 is one of the fastest-growing spaces on the web right now, with thousands of new projects emerging every week. Each project aims to fill a gap in the space by providing a new technology How do we keep up with documentation, and what should be prioritized for these projects as they scale?
Web3, also referred to as the read-write-own web, is a new form of the internet that utilizes technologies such as blockchain networks, cryptocurrency, crypto wallets, and digital assets like NFTs. The Web3 space is growing by the thousands every week, with new projects and technologies constantly emerging. As writers, it can be challenging to navigate through the space, make sense of every piece of new content, and understand what should be written about for others to read, and what will be irrelevant next week. Many of these new technologies are using pieces of code known as smart contracts or interacting with the APIs of multiple applications at once. What documentation are end-users looking for, and what is the most beneficial format for them to read and comprehend all of this new information? In this talk, I'll discuss what I've learned as a Senior Technical Writer for Filebase, a decentralized cloud storage provider at the heart of hundreds of Web3 projects, and what our customers have benefited from the most when it comes to documentation.
Why your API doesn’t solve my problem: A use case-driven API design
API docs frequently fail to address developers’ needs by omitting common usage scenarios and use cases. Let’s take a look at good and bad practices for documenting API use cases, and take steps to ensure that developers get from our API and docs what they really want.
You wrote an API specification, documented your endpoints, and published SDKs. Here’s a question, though: Does your API actually solve your users’ problems?
API providers often fail to address common use cases to solve users’ needs, or their assumptions don’t match the reality. This may end up in frustration and loss of users.
In this talk, we will take a peek into developers’ mindset. I will show how to better understand the developers’ needs by researching the usage patterns, existing libraries and 3rd party experience layers, provide examples of good and bad practices, and suggest actionable steps to improve developer experience for your API.
unREST among the docs
At times, you have to build docs that cover not only REST-y APIs but also frontend SDKs. What do you do, when you have to offer docs for multiple such SDKs, based on different frameworks, under rapid, uncoordinated development with multiple feature enhancements per iteration and at times, with breaking changes, but versioned and searchable?
Developing a best-in-class deprecation policy for your APIs
Nobody likes ambiguity—especially when it comes to the stability of APIs and the expectations for availability long term. Avoid common pitfalls and explore a critical area where trust is built with developers through thoughtful policy and the development of best-in-class documentation.
A good deprecation policy involves a lot of forward thinking and an awareness of how developers or end users are currently leveraging your capabilities, and how a given API or feature deprecation could affect them in the future. The hard-earned trust that you’ve built and maintained with these individuals is at risk with any type of policy or documentation that is unclear.
The road to developing a clear, trustworthy deprecation policy is a multi-faceted initiative with input from product, engineering, customer success and other cross-functional teams, as well as external market awareness.
Knowing which voices to have in the room, what the industry standards are, and formulating appropriate communication timelines will ensure a world class policy is developed and documented before it’s needed.
Join us as we dive into the nuances of this process and how to avoid the common pitfalls that come from lacking a strategic, thoughtful approach to documenting a deprecation policy for your APIs.
Annotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyone
At MongoDB, we now generate REST API references for MongoDB Atlas from annotations in the product’s source. Our team’s writers proposed, planned, led, and implemented this project–and learned a lot along the way. We’ll share how we got buy-in from engineering and product stakeholders, coordinated the project across teams, implemented swagger-core annotations in Java, and drove positive change to benefit our team, the company, and our users.
What do developers do when it comes to understanding and using APIs?
It turns out there is no single answer. Developers may have unique goals, motivations, constraints, and challenges, and all of these influence how they approach the problem in front of them. However, more than a decade ago, three development styles were identified - systematic, pragmatic, and opportunistic - and the academic literature suggests that these still exist today.
Two of the three approaches, the systematic and the opportunistic pattern, can be considered as opposite extremes, while the pragmatic approach is situated in between and is similar to both. It is not a personality trait - people may approach a situation one way or another depending on their circumstances, goals, and motivations (however, they may also have a preferred approach, which is usually their characteristic).
Understanding the differences between these patterns (and the different needs) helps us to design in a way that serves most of the users, and even helps them to get into a state of flow by providing the optimal level of challenge to solve their problem.
Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations
It's time to take the bias out of code, UI, docs, configurations, or our everyday language by ensuring we choose our words carefully to avoid harmful subtext or exclusion. We can do our part and take steps by examining assets from code to config files to API specifications to standards.
Heard of suss? You can suss out more information or you can find someone's information to be suss. "Suss" shows the flexibility of language. It’s an ongoing process to change how we use certain words. It's important to choose words carefully to convey the correct meaning and avoid harmful subtext or exclusion. Let's explore some of the tools and triage methods that it takes from an engineering viewpoint to make bias-free choices. How can you ensure that biased words do not sneak into code, UI, docs, configurations, or our everyday language?
First, let's walk through how to take an inventory of assets from code to config files to API specifications to standards. Next, by placing those findings into categories, prioritize the work to substitute with inclusive alternatives. Let's examine some examples using both API and code assets. Next is a demonstration of how to automate analyzing your source code or documentation with a linter, looking for patterns based on rules that are fed into the tool.
What's in the future for these efforts? Inclusive language should expand beyond English and North America efforts. To do so, let's organize the work with automation tooling, as engineers do.
Creating API documentation for international communities
How to create documentation and write code for an international audience, not just the people who speak and think like you. Make your APIs more useful for everyone on the planet.
Much of the documentation supplied by both Open Source and Close Souce projects assume the community have a good understanding of the English language and often North American culture as well. This creates barriers for many solution providers, who are the gateway to potentially huge markets for your project.
This talk discusses some of the cultural differences, particularly for people from Asia, in using English language API documentation. It suggests some strategies to help diverse audiences understand you APIs and create solutions using them.
The talk will cover not only differences in language but also other cultural differences that are often not obvious. For example:
Different expectations about publication formats, release processes, levels of support during the development process
Meeting and communications styles
Software development workflows, processes, and tools
Supporting people who are visually impaired will also be briefly discussed.
As well as discussing these issues, specific suggestions will be provided to make API docs accessible for as many people as possible.
This talk is based on Alec's work with customers in Europe, North America, Middle East, Asia, and Australasia. The last five have been spent as a developer evangelist working with PaperCut partners in China, Japan, Korea, US and Europe.
One Developer Portal to Document Them All
APIs in a modern enterprise are rarely uniform or all of the same type. The multitude of API types can be due to organic growth, mergers and acquisitions, or any number of other reasons. Regardless of their origin, APIs of all types need to be fully documented to facilitate a developer’s journey as they interact with your API ecosystem in order to develop useful applications. In this talk I will show examples of how we have augmented developer portals to document APIs that are not of the REST variety, such as AsyncAPI, GraphQL, SOAP, gRPC, and more, such that all API documentation can seamlessly live side-by-side.
Docs-as-Code: Evolving the API Documentation Experience
We are a software engineering team creating API docs. Docs are authored using Instructional Design principles to narrate use-cases and practical API implementations. This talk shares why & how we've applied software development practices to evolve our document tooling, creation, & delivery methods.
Our APIs describe asynchronous protocols used for embedded software (firmware) components in a digital 2-way radio communications system. The API is protocol data unit (PDU) based and its definition is described in a proprietary format; consequently, well-known API formats, such as Swagger/OpenAPI, or tools, such as doxygen, are not used.
Our product training and technical writing teams are very experienced in Instructional Design methods, but these teams have only written documentation for an end-user audience. Understanding software development processes is equally important as understanding two-way radio networks in order to successfully integrate with the APIs. This is the rationale for having a software engineering team develop the skillsets to write API documentation for a developer audience.
With a solid foundation of API documentation in place, regular examination of engineering efficiency and developer experience is appropriate. Repeated actions can be replaced by automation. Content can be modular and re-usable. Formats can be streamlined for easier consumption. Docs can be made portable and lightweight for faster delivery.
Developer journey - make it easy for devs to love your product
Ever wonder how some products are just lovable and easy to use while other are not? The good products have optimized onboarding into their ecosystem where you get the information served at the right time.
That’s thanks to developer journey and we will teach you how to get it right!
We will go through the basics such as how to analyze existing and non-existing developer touchpoints, set metrics and optimize them to increase the conversion.
Complexity is not complicatedness
Deliberate Complexity Conferences - 19 JULY 2022
Alicia Juarrero - Complexity is not complicatedness
Professor Alicia Juarrero, a leading complexity theory philosopher and academic, as well as the founder and president of VectorAnalytica, a technology company that specializes in large scale scientific data capture and real time analysis tools. Alicia's work in complexity theory is widely quoted by thought leaders in the technology space and referenced in many recent complexity-informed approaches for managing highly dynamic systems, as well as in knowledge management.
How cognitive biases and ranking can foster an ineffective architecture and d...
Deliberate Complexity Conferences - Building Successful Platforms and APIs (29 June). Kenny Baas-Schwegler & Evelyn van Kelle - How cognitive biases and ranking can foster an ineffective architecture and design
APIs: Semi-permeable, osmotic interfaces
Deliberate Complexity Conferences - Building Successful Platforms and APIs (29 June). Dawn Ahukanna - APIs: Semi-permeable, osmotic interfaces.
How to develop an API ecosystem in the fintech industry from the ground up
In this talk, we are going to explain what we did @ MODO (a new mobile payment solution similar to Bizum) to develop from the ground up a single platform that provides multiple functionalities to the biggest banks in Argentina, using OpenAPI/Swagger and a design-first approach.
Open sourcing Adyen’s API explorer
Two years ago, Adyen realized the Swagger UI wasn’t meeting their needs... so they decided to build their own. We’ll share how we designed and built our new API Explorer - making it more extendable, and easier for Developers and Technical Writers to maintain. We’ll also talk about our future plans, including open sourcing it for the community.
Creating Interactive Docs with Postman
The story of how our small team automated our way to fully customized, interactive API documentation in Postman–including visualizations, example responses, and an OpenAPI-esque object models section. Along the way, we open-sourced much of the workflow and happened to win a hackathon.
The Joy of Docs, or, Technical Writing for Developers and Engineers
Technical writing is rarely taught in code schools or listed among the qualifications for an engineering job. Yet developers rely heavily on documentation to use the tools they need to use. Not only that, decisions about which tool to use often take into account the availability of quality documentation. It’s important not to leave the task of writing docs to technical writers who may not fully understand the underlying technology or use cases. This talk will teach you the basics of technical writing–from tutorials and API reference guides to pull requests, release notes, and even code comments - so you can increase adoption of your software and keep the developers using it happy.
Measure and improve API references with use cases: challenges and best practice
I’d like to share how technical writers can pair up with product and development teams to measure and improve API references usability with additional content: use cases and best practices. We’ll take a closer look at the API design challenges and practical solutions.
We’ll touch on the importance of spotting development and product biases when designing and developing the APIs, especially if technical writers were not involved in the process early on. I’ll share examples of how I work with multiple teams and manage dependencies, the tools we use, and the organizational methods we rely on to collaborate effectively.
I will guide everyone through an API reference review example and discuss how writers can use API reviews as a way to get everyone, from design to development, on the same page.
Blood, sweat, and creating an API handbook
This talk describes the development of ABN AMRO’s API handbook, the single-source of truth for the development and management of internal and external API products.
Our company is moving towards an API-First culture and mentality. Streamlining the development process is key to enabling this. In the beginning, API development knowledge was not documented or centralized in one location. Accurate information was not available for developer teams and they were not aware of what exactly the process entailed.
My colleague and I began by making agreements on how the overall process works, describing it in an intuitive way, and then by making it open and accessible company-wide. This involved setting up and hosting face-to-face meetings or MS Teams calls with specialists to find out what was required
This talk describes our approach to gathering content from experts, defining and refining processes, obtaining feedback from readers, and redesigning the content in a more user-centric format.
Leveraging API Docs and Tools at Mercedes-Benz /developers
This talk walks along the developer portal journey, the steps taken to improve DX, challenges the team tackled with from its corporate context and the growth of data products of the platform. A special focus will be placed on API docs and dev tools.
みなさんこんにちはこれ何文字まで入るの？40文字以下不可とか本当に意味わからないけどこれ限界文字数書いてないからマジでやばい文字数いけるんじゃないの？えこ...
ここ3000字までしか入らないけどタイトルの方がたくさん文字入ると思います。
Elizabeth Buie - Older adults: Are we really designing for our future selves?
Elizabeth Buie - Older adults: Are we really designing for our future selves?
More Related Content
More from Pronovix
Why your API doesn’t solve my problem: A use case-driven API design
API docs frequently fail to address developers’ needs by omitting common usage scenarios and use cases. Let’s take a look at good and bad practices for documenting API use cases, and take steps to ensure that developers get from our API and docs what they really want.
You wrote an API specification, documented your endpoints, and published SDKs. Here’s a question, though: Does your API actually solve your users’ problems?
API providers often fail to address common use cases to solve users’ needs, or their assumptions don’t match the reality. This may end up in frustration and loss of users.
In this talk, we will take a peek into developers’ mindset. I will show how to better understand the developers’ needs by researching the usage patterns, existing libraries and 3rd party experience layers, provide examples of good and bad practices, and suggest actionable steps to improve developer experience for your API.
unREST among the docs
At times, you have to build docs that cover not only REST-y APIs but also frontend SDKs. What do you do, when you have to offer docs for multiple such SDKs, based on different frameworks, under rapid, uncoordinated development with multiple feature enhancements per iteration and at times, with breaking changes, but versioned and searchable?
Developing a best-in-class deprecation policy for your APIs
Nobody likes ambiguity—especially when it comes to the stability of APIs and the expectations for availability long term. Avoid common pitfalls and explore a critical area where trust is built with developers through thoughtful policy and the development of best-in-class documentation.
A good deprecation policy involves a lot of forward thinking and an awareness of how developers or end users are currently leveraging your capabilities, and how a given API or feature deprecation could affect them in the future. The hard-earned trust that you’ve built and maintained with these individuals is at risk with any type of policy or documentation that is unclear.
The road to developing a clear, trustworthy deprecation policy is a multi-faceted initiative with input from product, engineering, customer success and other cross-functional teams, as well as external market awareness.
Knowing which voices to have in the room, what the industry standards are, and formulating appropriate communication timelines will ensure a world class policy is developed and documented before it’s needed.
Join us as we dive into the nuances of this process and how to avoid the common pitfalls that come from lacking a strategic, thoughtful approach to documenting a deprecation policy for your APIs.
Annotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyone
At MongoDB, we now generate REST API references for MongoDB Atlas from annotations in the product’s source. Our team’s writers proposed, planned, led, and implemented this project–and learned a lot along the way. We’ll share how we got buy-in from engineering and product stakeholders, coordinated the project across teams, implemented swagger-core annotations in Java, and drove positive change to benefit our team, the company, and our users.
What do developers do when it comes to understanding and using APIs?
It turns out there is no single answer. Developers may have unique goals, motivations, constraints, and challenges, and all of these influence how they approach the problem in front of them. However, more than a decade ago, three development styles were identified - systematic, pragmatic, and opportunistic - and the academic literature suggests that these still exist today.
Two of the three approaches, the systematic and the opportunistic pattern, can be considered as opposite extremes, while the pragmatic approach is situated in between and is similar to both. It is not a personality trait - people may approach a situation one way or another depending on their circumstances, goals, and motivations (however, they may also have a preferred approach, which is usually their characteristic).
Understanding the differences between these patterns (and the different needs) helps us to design in a way that serves most of the users, and even helps them to get into a state of flow by providing the optimal level of challenge to solve their problem.
Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations
It's time to take the bias out of code, UI, docs, configurations, or our everyday language by ensuring we choose our words carefully to avoid harmful subtext or exclusion. We can do our part and take steps by examining assets from code to config files to API specifications to standards.
Heard of suss? You can suss out more information or you can find someone's information to be suss. "Suss" shows the flexibility of language. It’s an ongoing process to change how we use certain words. It's important to choose words carefully to convey the correct meaning and avoid harmful subtext or exclusion. Let's explore some of the tools and triage methods that it takes from an engineering viewpoint to make bias-free choices. How can you ensure that biased words do not sneak into code, UI, docs, configurations, or our everyday language?
First, let's walk through how to take an inventory of assets from code to config files to API specifications to standards. Next, by placing those findings into categories, prioritize the work to substitute with inclusive alternatives. Let's examine some examples using both API and code assets. Next is a demonstration of how to automate analyzing your source code or documentation with a linter, looking for patterns based on rules that are fed into the tool.
What's in the future for these efforts? Inclusive language should expand beyond English and North America efforts. To do so, let's organize the work with automation tooling, as engineers do.
Creating API documentation for international communities
How to create documentation and write code for an international audience, not just the people who speak and think like you. Make your APIs more useful for everyone on the planet.
Much of the documentation supplied by both Open Source and Close Souce projects assume the community have a good understanding of the English language and often North American culture as well. This creates barriers for many solution providers, who are the gateway to potentially huge markets for your project.
This talk discusses some of the cultural differences, particularly for people from Asia, in using English language API documentation. It suggests some strategies to help diverse audiences understand you APIs and create solutions using them.
The talk will cover not only differences in language but also other cultural differences that are often not obvious. For example:
Different expectations about publication formats, release processes, levels of support during the development process
Meeting and communications styles
Software development workflows, processes, and tools
Supporting people who are visually impaired will also be briefly discussed.
As well as discussing these issues, specific suggestions will be provided to make API docs accessible for as many people as possible.
This talk is based on Alec's work with customers in Europe, North America, Middle East, Asia, and Australasia. The last five have been spent as a developer evangelist working with PaperCut partners in China, Japan, Korea, US and Europe.
One Developer Portal to Document Them All
APIs in a modern enterprise are rarely uniform or all of the same type. The multitude of API types can be due to organic growth, mergers and acquisitions, or any number of other reasons. Regardless of their origin, APIs of all types need to be fully documented to facilitate a developer’s journey as they interact with your API ecosystem in order to develop useful applications. In this talk I will show examples of how we have augmented developer portals to document APIs that are not of the REST variety, such as AsyncAPI, GraphQL, SOAP, gRPC, and more, such that all API documentation can seamlessly live side-by-side.
Docs-as-Code: Evolving the API Documentation Experience
We are a software engineering team creating API docs. Docs are authored using Instructional Design principles to narrate use-cases and practical API implementations. This talk shares why & how we've applied software development practices to evolve our document tooling, creation, & delivery methods.
Our APIs describe asynchronous protocols used for embedded software (firmware) components in a digital 2-way radio communications system. The API is protocol data unit (PDU) based and its definition is described in a proprietary format; consequently, well-known API formats, such as Swagger/OpenAPI, or tools, such as doxygen, are not used.
Our product training and technical writing teams are very experienced in Instructional Design methods, but these teams have only written documentation for an end-user audience. Understanding software development processes is equally important as understanding two-way radio networks in order to successfully integrate with the APIs. This is the rationale for having a software engineering team develop the skillsets to write API documentation for a developer audience.
With a solid foundation of API documentation in place, regular examination of engineering efficiency and developer experience is appropriate. Repeated actions can be replaced by automation. Content can be modular and re-usable. Formats can be streamlined for easier consumption. Docs can be made portable and lightweight for faster delivery.
Developer journey - make it easy for devs to love your product
Ever wonder how some products are just lovable and easy to use while other are not? The good products have optimized onboarding into their ecosystem where you get the information served at the right time.
That’s thanks to developer journey and we will teach you how to get it right!
We will go through the basics such as how to analyze existing and non-existing developer touchpoints, set metrics and optimize them to increase the conversion.
Complexity is not complicatedness
Deliberate Complexity Conferences - 19 JULY 2022
Alicia Juarrero - Complexity is not complicatedness
Professor Alicia Juarrero, a leading complexity theory philosopher and academic, as well as the founder and president of VectorAnalytica, a technology company that specializes in large scale scientific data capture and real time analysis tools. Alicia's work in complexity theory is widely quoted by thought leaders in the technology space and referenced in many recent complexity-informed approaches for managing highly dynamic systems, as well as in knowledge management.
How cognitive biases and ranking can foster an ineffective architecture and d...
Deliberate Complexity Conferences - Building Successful Platforms and APIs (29 June). Kenny Baas-Schwegler & Evelyn van Kelle - How cognitive biases and ranking can foster an ineffective architecture and design
APIs: Semi-permeable, osmotic interfaces
Deliberate Complexity Conferences - Building Successful Platforms and APIs (29 June). Dawn Ahukanna - APIs: Semi-permeable, osmotic interfaces.
How to develop an API ecosystem in the fintech industry from the ground up
In this talk, we are going to explain what we did @ MODO (a new mobile payment solution similar to Bizum) to develop from the ground up a single platform that provides multiple functionalities to the biggest banks in Argentina, using OpenAPI/Swagger and a design-first approach.
Open sourcing Adyen’s API explorer
Two years ago, Adyen realized the Swagger UI wasn’t meeting their needs... so they decided to build their own. We’ll share how we designed and built our new API Explorer - making it more extendable, and easier for Developers and Technical Writers to maintain. We’ll also talk about our future plans, including open sourcing it for the community.
Creating Interactive Docs with Postman
The story of how our small team automated our way to fully customized, interactive API documentation in Postman–including visualizations, example responses, and an OpenAPI-esque object models section. Along the way, we open-sourced much of the workflow and happened to win a hackathon.
The Joy of Docs, or, Technical Writing for Developers and Engineers
Technical writing is rarely taught in code schools or listed among the qualifications for an engineering job. Yet developers rely heavily on documentation to use the tools they need to use. Not only that, decisions about which tool to use often take into account the availability of quality documentation. It’s important not to leave the task of writing docs to technical writers who may not fully understand the underlying technology or use cases. This talk will teach you the basics of technical writing–from tutorials and API reference guides to pull requests, release notes, and even code comments - so you can increase adoption of your software and keep the developers using it happy.
Measure and improve API references with use cases: challenges and best practice
I’d like to share how technical writers can pair up with product and development teams to measure and improve API references usability with additional content: use cases and best practices. We’ll take a closer look at the API design challenges and practical solutions.
We’ll touch on the importance of spotting development and product biases when designing and developing the APIs, especially if technical writers were not involved in the process early on. I’ll share examples of how I work with multiple teams and manage dependencies, the tools we use, and the organizational methods we rely on to collaborate effectively.
I will guide everyone through an API reference review example and discuss how writers can use API reviews as a way to get everyone, from design to development, on the same page.
Blood, sweat, and creating an API handbook
This talk describes the development of ABN AMRO’s API handbook, the single-source of truth for the development and management of internal and external API products.
Our company is moving towards an API-First culture and mentality. Streamlining the development process is key to enabling this. In the beginning, API development knowledge was not documented or centralized in one location. Accurate information was not available for developer teams and they were not aware of what exactly the process entailed.
My colleague and I began by making agreements on how the overall process works, describing it in an intuitive way, and then by making it open and accessible company-wide. This involved setting up and hosting face-to-face meetings or MS Teams calls with specialists to find out what was required
This talk describes our approach to gathering content from experts, defining and refining processes, obtaining feedback from readers, and redesigning the content in a more user-centric format.
Leveraging API Docs and Tools at Mercedes-Benz /developers
This talk walks along the developer portal journey, the steps taken to improve DX, challenges the team tackled with from its corporate context and the growth of data products of the platform. A special focus will be placed on API docs and dev tools.
More from Pronovix (20)
Why your API doesn’t solve my problem: A use case-driven API design
Why your API doesn’t solve my problem: A use case-driven API design
Developing a best-in-class deprecation policy for your APIs
Developing a best-in-class deprecation policy for your APIs
Annotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyone
Annotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyone
What do developers do when it comes to understanding and using APIs?
What do developers do when it comes to understanding and using APIs?
Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations
Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations
Creating API documentation for international communities
Creating API documentation for international communities
Docs-as-Code: Evolving the API Documentation Experience
Docs-as-Code: Evolving the API Documentation Experience
Developer journey - make it easy for devs to love your product
Developer journey - make it easy for devs to love your product
How cognitive biases and ranking can foster an ineffective architecture and d...
How cognitive biases and ranking can foster an ineffective architecture and d...
How to develop an API ecosystem in the fintech industry from the ground up
How to develop an API ecosystem in the fintech industry from the ground up
The Joy of Docs, or, Technical Writing for Developers and Engineers
The Joy of Docs, or, Technical Writing for Developers and Engineers
Measure and improve API references with use cases: challenges and best practice
Measure and improve API references with use cases: challenges and best practice
Leveraging API Docs and Tools at Mercedes-Benz /developers
Leveraging API Docs and Tools at Mercedes-Benz /developers
Recently uploaded
みなさんこんにちはこれ何文字まで入るの？40文字以下不可とか本当に意味わからないけどこれ限界文字数書いてないからマジでやばい文字数いけるんじゃないの？えこ...
ここ3000字までしか入らないけどタイトルの方がたくさん文字入ると思います。
Elizabeth Buie - Older adults: Are we really designing for our future selves?
Elizabeth Buie - Older adults: Are we really designing for our future selves?
Uni Systems Copilot event_05062024_C.Vlachos.pdf
Unlocking Productivity: Leveraging the Potential of Copilot in Microsoft 365, a presentation by Christoforos Vlachos, Senior Solutions Manager – Modern Workplace, Uni Systems
Securing your Kubernetes cluster_ a step-by-step guide to success !
Today, after several years of existence, an extremely active community and an ultra-dynamic ecosystem, Kubernetes has established itself as the de facto standard in container orchestration. Thanks to a wide range of managed services, it has never been so easy to set up a ready-to-use Kubernetes cluster.
However, this ease of use means that the subject of security in Kubernetes is often left for later, or even neglected. This exposes companies to significant risks.
In this talk, I'll show you step-by-step how to secure your Kubernetes cluster for greater peace of mind and reliability.
GraphSummit Singapore | The Future of Agility: Supercharging Digital Transfor...
Leonard Jayamohan, Partner & Generative AI Lead, Deloitte
This keynote will reveal how Deloitte leverages Neo4j’s graph power for groundbreaking digital twin solutions, achieving a staggering 100x performance boost. Discover the essential role knowledge graphs play in successful generative AI implementations. Plus, get an exclusive look at an innovative Neo4j + Generative AI solution Deloitte is developing in-house.
20240605 QFM017 Machine Intelligence Reading List May 2024
Everything I found interesting about machines behaving intelligently during May 2024
GraphSummit Singapore | Enhancing Changi Airport Group's Passenger Experience...
Dr. Sean Tan, Head of Data Science, Changi Airport Group
Discover how Changi Airport Group (CAG) leverages graph technologies and generative AI to revolutionize their search capabilities. This session delves into the unique search needs of CAG’s diverse passengers and customers, showcasing how graph data structures enhance the accuracy and relevance of AI-generated search results, mitigating the risk of “hallucinations” and improving the overall customer journey.
UiPath Test Automation using UiPath Test Suite series, part 6
Welcome to UiPath Test Automation using UiPath Test Suite series part 6. In this session, we will cover Test Automation with generative AI and Open AI.
UiPath Test Automation with generative AI and Open AI webinar offers an in-depth exploration of leveraging cutting-edge technologies for test automation within the UiPath platform. Attendees will delve into the integration of generative AI, a test automation solution, with Open AI advanced natural language processing capabilities.
Throughout the session, participants will discover how this synergy empowers testers to automate repetitive tasks, enhance testing accuracy, and expedite the software testing life cycle. Topics covered include the seamless integration process, practical use cases, and the benefits of harnessing AI-driven automation for UiPath testing initiatives. By attending this webinar, testers, and automation professionals can gain valuable insights into harnessing the power of AI to optimize their test automation workflows within the UiPath ecosystem, ultimately driving efficiency and quality in software development processes.
What will you get from this session?
1. Insights into integrating generative AI.
2. Understanding how this integration enhances test automation within the UiPath platform
3. Practical demonstrations
4. Exploration of real-world use cases illustrating the benefits of AI-driven test automation for UiPath
Topics covered:
What is generative AI
Test Automation with generative AI and Open AI.
UiPath integration with generative AI
Speaker:
Deepak Rai, Automation Practice Lead, Boundaryless Group and UiPath MVP
Communications Mining Series - Zero to Hero - Session 1
This session provides introduction to UiPath Communication Mining, importance and platform overview. You will acquire a good understand of the phases in Communication Mining as we go over the platform with you. Topics covered:
• Communication Mining Overview
• Why is it important?
• How can it help today’s business and the benefits
• Phases in Communication Mining
• Demo on Platform overview
• Q/A
20240607 QFM018 Elixir Reading List May 2024
Everything I found interesting about the Elixir programming ecosystem in May 2024
Video Streaming: Then, Now, and in the Future
In his public lecture, Christian Timmerer provides insights into the fascinating history of video streaming, starting from its humble beginnings before YouTube to the groundbreaking technologies that now dominate platforms like Netflix and ORF ON. Timmerer also presents provocative contributions of his own that have significantly influenced the industry. He concludes by looking at future challenges and invites the audience to join in a discussion.
20240609 QFM020 Irresponsible AI Reading List May 2024
Everything I found interesting about the irresponsible use of machine intelligence in May 2024
Large Language Model (LLM) and it’s Geospatial Applications
Large Language Model (LLM) and it’s Geospatial Applications.
Generative AI Deep Dive: Advancing from Proof of Concept to Production
Join Maher Hanafi, VP of Engineering at Betterworks, in this new session where he'll share a practical framework to transform Gen AI prototypes into impactful products! He'll delve into the complexities of data collection and management, model selection and optimization, and ensuring security, scalability, and responsible use.
Artificial Intelligence for XMLDevelopment
In the rapidly evolving landscape of technologies, XML continues to play a vital role in structuring, storing, and transporting data across diverse systems. The recent advancements in artificial intelligence (AI) present new methodologies for enhancing XML development workflows, introducing efficiency, automation, and intelligent capabilities. This presentation will outline the scope and perspective of utilizing AI in XML development. The potential benefits and the possible pitfalls will be highlighted, providing a balanced view of the subject.
We will explore the capabilities of AI in understanding XML markup languages and autonomously creating structured XML content. Additionally, we will examine the capacity of AI to enrich plain text with appropriate XML markup. Practical examples and methodological guidelines will be provided to elucidate how AI can be effectively prompted to interpret and generate accurate XML markup.
Further emphasis will be placed on the role of AI in developing XSLT, or schemas such as XSD and Schematron. We will address the techniques and strategies adopted to create prompts for generating code, explaining code, or refactoring the code, and the results achieved.
The discussion will extend to how AI can be used to transform XML content. In particular, the focus will be on the use of AI XPath extension functions in XSLT, Schematron, Schematron Quick Fixes, or for XML content refactoring.
The presentation aims to deliver a comprehensive overview of AI usage in XML development, providing attendees with the necessary knowledge to make informed decisions. Whether you’re at the early stages of adopting AI or considering integrating it in advanced XML development, this presentation will cover all levels of expertise.
By highlighting the potential advantages and challenges of integrating AI with XML development tools and languages, the presentation seeks to inspire thoughtful conversation around the future of XML development. We’ll not only delve into the technical aspects of AI-powered XML development but also discuss practical implications and possible future directions.
Pushing the limits of ePRTC: 100ns holdover for 100 days
At WSTS 2024, Alon Stern explored the topic of parametric holdover and explained how recent research findings can be implemented in real-world PNT networks to achieve 100 nanoseconds of accuracy for up to 100 days.
Removing Uninteresting Bytes in Software Fuzzing
Imagine a world where software fuzzing, the process of mutating bytes in test seeds to uncover hidden and erroneous program behaviors, becomes faster and more effective. A lot depends on the initial seeds, which can significantly dictate the trajectory of a fuzzing campaign, particularly in terms of how long it takes to uncover interesting behaviour in your code. We introduce DIAR, a technique designed to speedup fuzzing campaigns by pinpointing and eliminating those uninteresting bytes in the seeds. Picture this: instead of wasting valuable resources on meaningless mutations in large, bloated seeds, DIAR removes the unnecessary bytes, streamlining the entire process.
In this work, we equipped AFL, a popular fuzzer, with DIAR and examined two critical Linux libraries -- Libxml's xmllint, a tool for parsing xml documents, and Binutil's readelf, an essential debugging and security analysis command-line tool used to display detailed information about ELF (Executable and Linkable Format). Our preliminary results show that AFL+DIAR does not only discover new paths more quickly but also achieves higher coverage overall. This work thus showcases how starting with lean and optimized seeds can lead to faster, more comprehensive fuzzing campaigns -- and DIAR helps you find such seeds.
- These are slides of the talk given at IEEE International Conference on Software Testing Verification and Validation Workshop, ICSTW 2022.
Recently uploaded (20)
みなさんこんにちはこれ何文字まで入るの？40文字以下不可とか本当に意味わからないけどこれ限界文字数書いてないからマジでやばい文字数いけるんじゃないの？えこ...
みなさんこんにちはこれ何文字まで入るの？40文字以下不可とか本当に意味わからないけどこれ限界文字数書いてないからマジでやばい文字数いけるんじゃないの？えこ...
Elizabeth Buie - Older adults: Are we really designing for our future selves?
Elizabeth Buie - Older adults: Are we really designing for our future selves?
Securing your Kubernetes cluster_ a step-by-step guide to success !
Securing your Kubernetes cluster_ a step-by-step guide to success !
GraphSummit Singapore | The Future of Agility: Supercharging Digital Transfor...
GraphSummit Singapore | The Future of Agility: Supercharging Digital Transfor...
20240605 QFM017 Machine Intelligence Reading List May 2024
20240605 QFM017 Machine Intelligence Reading List May 2024
GraphSummit Singapore | Enhancing Changi Airport Group's Passenger Experience...
GraphSummit Singapore | Enhancing Changi Airport Group's Passenger Experience...
UiPath Test Automation using UiPath Test Suite series, part 6
UiPath Test Automation using UiPath Test Suite series, part 6
Communications Mining Series - Zero to Hero - Session 1
Communications Mining Series - Zero to Hero - Session 1
20240609 QFM020 Irresponsible AI Reading List May 2024
20240609 QFM020 Irresponsible AI Reading List May 2024
Large Language Model (LLM) and it’s Geospatial Applications
Large Language Model (LLM) and it’s Geospatial Applications
Generative AI Deep Dive: Advancing from Proof of Concept to Production
Generative AI Deep Dive: Advancing from Proof of Concept to Production
Pushing the limits of ePRTC: 100ns holdover for 100 days
Pushing the limits of ePRTC: 100ns holdover for 100 days
Secstrike : Reverse Engineering & Pwnable tools for CTF.pptx
Secstrike : Reverse Engineering & Pwnable tools for CTF.pptx
Increasing API Adoption via a Code Playground
- 1. Code S. Adeel Ali | adeel@apimatic.io @APIMatic | @AdeelAli25
- 11. Don’t Make Me Code https://medium.com/the-opsee-blog/let-s-talk-about-developer-experience-dx-design- @APIMatic | @AdeelAli25
- 12. Product/API Adoption @APIMatic | @AdeelAli25 ∝
- 13. ∝ Achieving the User Goal in the Least Possible • Number of Steps • Time @APIMatic | @AdeelAli25
- 14. ∝ Getting Started / Ref Docs Sample App Code Authentication Code API Interaction Code API DX = Least Steps & Time to the First Hello World Hello World @APIMatic | @AdeelAli25
- 15. Checks and Validations Encode Inputs Serialize body Build HTTP request Make HTTP Call Deserialize body Decode to output Handle errors Getting Started Docs Configuration API Call Arguments Authentication ∝ Hello World @APIMatic | @AdeelAli25 API DX = Least Steps & Time to the First Hello World
- 16. API Call Arguments Encode Inputs Serialize body Build HTTP request Make HTTP Call Deserialize body Decode to output 4 - Static 1 - Static 2 - Interactive 3 - Interactive ∝ Hello World @APIMatic | @AdeelAli25 API DX = Least Steps & Time to the First Hello World
- 17. API Call Arguments Encode Inputs Serialize body Build HTTP request Make HTTP Call Deserialize body Decode to output 4 – SDKs/Client Libraries 1- Getting Started 2 – Dynamic Code Samples 3 – Assisted Auth ∝ Hello World @APIMatic | @AdeelAli25 API DX = Least Steps & Time to the First Hello World
- 18. API Call Arguments Encode Inputs Serialize body Build HTTP request Make HTTP Call Deserialize body Decode to output 4 – SDKs/Client Libraries 1- Getting Started 2 – Dynamic Code Samples 3 – Assisted Auth Hello World @APIMatic | @AdeelAli25
- 19. API Call Arguments Encode Inputs Serialize body Build HTTP request Make HTTP Call Deserialize body Decode to output 4 – SDKs/Client Libraries 1- Getting Started 2 – Dynamic Code Samples 3 – Assisted Auth Hello World Not just a cost saver, but in fact a revenue generator — Andrew Cowell, Head of Innovation, Earthport @APIMatic | @AdeelAli25
- 20. • Your developers should be using your API like they use any other product • For the best DX, Don’t make them code. • Give them what they need to get started. Let them focus on what they ar @APIMatic | @AdeelAli25
- 22. DX @APIMatic | @AdeelAli25 Thank You If you talk to a man in a language he understands, that goes to his head. If you talk to him in his language, that goes to his heart
Editor's Notes
- This Photo by Unknown Author is licensed under CC BY-SA
- This Photo by Unknown Author is licensed under CC BY-SA
- This Photo by Unknown Author is licensed under CC BY-SA
- This Photo by Unknown Author is licensed under CC BY-SA
- This Photo by Unknown Author is licensed under CC BY-SA
- This Photo by Unknown Author is licensed under CC BY-SA
- This Photo by Unknown Author is licensed under CC BY-SA
- This Photo by Unknown Author is licensed under CC BY-SA
- This Photo by Unknown Author is licensed under CC BY-SA
- This Photo by Unknown Author is licensed under CC BY-SA
- This Photo by Unknown Author is licensed under CC BY-SA
- This Photo by Unknown Author is licensed under CC BY-SA
- This Photo by Unknown Author is licensed under CC BY-SA