Lessons Learned from Revamping Our Doc Site

•

0 likes•671 views

Learn what went well and what didn’t, when Ilona, a technical writer, and Prabhjot, a software engineer, share the story of revamping the developer documentation website at Twitch. Some hints: getting it done required more than just engineering, content, and design. Together they learned how to “manage up” and that the whole project went better because they worked so well as a team.

Technology

Lessons learned from revamping
our doc site
API Days, Paris
December, 2019
Ilona Koren-Deutsch
Prabhjot Singh

Prabhjot Singh
• Engineering the Twitch API
• More comfortable with Golang than French
• Still plays games written in the 90s

Ilona
Koren-Deutsch
● Technical Documentation Manager
● Trained chef and former academic
● Really bad at Super Smash Bros

Needs Analysis
If your API is the product, the
documentation is the user interface.

Squad Goals
● Increased user satisfaction
● Fewer (and shorter) calls for support
● More people using our APIs
● More and better mods and
extensions

Mods and
Extensions • Create ways for viewers and
streamers to interact
• Offer special offers, content, or
in-game items to Twitch viewers
• Let streamers to show off what
mods they are playing to their
community so they can download
and play the mod with their favorite
streamer

API doc must
include:
● Authentication
● Status codes
● Error messages
● Sample code
● Terms of use
● Changelog

Models for
excellent
developer
portals
The 2019 DevPortal Awards winners:
• Best API Reference Documentation:
Adyen API Explorer
• Best New DX Innovation: NBG Technology
Hub
• Best Onboarding: Nexmo Developer
• Best Accessible DevPortal: Barclays API
Exchange

Best in Show
API docs
● TomTom Developer Portal
● Quali Community
● Genesys PureCloud Developer Center
● Stripe
● Heroku
● Twilio

Issues with
the current
API docs
• Difﬁcult CMS
• Enormous amount of engineering
time
• Code that devs can’t
copy-and-paste
• Feedback in too many places
• Dev forums
• Discord
• Informal

OpenAPI
“The ability of APIs to describe their own
structure is the root of all awesomeness
in OpenAPI. “

OpenAPI
Allows you to describe your entire API,
including:
● Available endpoints and
operations on each endpoint
● Operation parameters
● Authentication methods
● Contact information, license,
terms of use and other
information

Solves our
problems
● Comprehensive API Documentation
● Easy Auto-Generation
● Automates Contract Testing
● Can build Mock APIs

Planning • Explore pain-points with the existing
documentation process
• Examine industry practices to set goals
for our docs
• Evaluate OpenAPI Spec as the source of
truth and collaboration for our docs
• Share opinions around different
workﬂows and reach an agreement
around the process for collaborating
over, creating and maintaining docs

Prabhjot: singhfqp@twitch.tv (Twitch: mangotreebird)
Ilona: korendeu@twitch.tv (Twitch: cycene) (Discord: cycene)

Reference
Mermade/widdershins
https://github.com/Mermade/widdershins
Slate Docs
https://github.com/slatedocs/slate

It is really hard to chose the right technology to use to build your devportal. The various types of devportals support 3 authoring experiences: -CMS based authoring - tight coupling between the content model and a UI -docs as code - code repo, or file based CMS -API based authoring - command line/endpoint as the interface We will discuss how things can go wrong if you don’t cater to your different authors

Lessons learned: Choosing your documentation system

Pronovix

My team faced several questions a year ago when we started our brand new documentation portal. - Are we going to set up a platform based on an existing solution? - Are we going to create our own platform? - Are we going to use existing internal tools like Confluence? To answer those questions we created our own process to guide our decision making: - First create a vision how your documentation should look like - Then test as many platforms as possible - Realize non are quite what you want - Realise you do not want to reinvent the wheel - Figure out how you can glue different solution together to get exactly what you want We ended up with a mix of existing technologies like Doxygen and Sphinx, glued together with custom python scripts. This allowed us to rely on proven technology and still have the flexibility to tweak the result to our requirements, getting the best of both worlds. The biggest benefit of our solution is that it uses Unit tests to ensure that the documentation and the API stay in sync and developers are forced to update documentation when they change the API. This was one of the biggest benefits we gained from our new documentation system compared to the previously used. In this talk I will go into detail how we created and implemented our process, how it worked out for us and why your team might want to follow a similar process. At the end of the talk you will have a better understanding of - How to do research and compare documentation platforms - How to perform an informed decision for their documentation needs - How not quite reinvent the wheel and get what you want.

Advancing Your API Strategy in an Infrastructure World

Pronovix

Leaping Forward: Finding The Future of Your API Docs

Pronovix

GraphQL vs BFF: A critical perspective

Pronovix

Imagine an application that has a web and a mobile, IOS and Android, or that your API is consumed by similar frontends from totally different teams. The functionalities they provide are distinct, hence the need for distinct sets of data and functions. You might think that the solution for this is having an “as generic as possible” backend for all UI’s. From my experience, this kind of backend leads to big issues in matters of performance, entangled user experience as well as extra and unnecessary communication for the development teams in order to align and meet their needs. Fortunately, there is a promising set of approaches taking the stage as they are created with the intention to optimize how front-end applications collaborate with back-ends: BFF (Backend-For-Frontend) pattern and GraphQL. Given these two approaches, which one is the right to consider? Join me in a talk where we will discuss the two approaches, underline both their good and bad sides, and determine which you should consider as the backend technology for your frontend application.

Designing APIs with OpenAPI Spec

Adam Paxton

API SDK Development – Lessons Learned

Pronovix

Building a solid API is a challenge but getting our APIs to be adopted by a larger audience, we quickly realized that having solid SDKs is the key element. At Rubrik we have been developing SDKs to supplement our APIs for over 3 years and during this process we have been making sure our SDKs provide a seamless experience for end-users to consume. When breaking API changes occur during the development of our product. The key takeaways of this session are: * How to strategize SDK development against an ever-changing API * Securely open-source your SDK development process

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.

Let Writers Write: Automating the Boring Stuff for Our Docs Team

Pronovix

We got into technical writing to make complex things seem simple, not to be janitors. So why do we spend so much of our time on maintenance? We fix broken links, find missing images, remove sensitive information... and that's only if we know these problems exist! Worst of all, we manually create and update code samples. Broken code samples are useless at best, and downright maddening at worst. Developer experience is really important to Adyen, and we got sick of seeing code samples become inconsistent and inaccurate. In this talk, Patrick Hammond will explain how Adyen approached the problem of creating, updating, and testing code samples. He'll discuss the solution they created, and how it works for their team. He'll also delve into some other common bugbears that Adyen are automating away, much to the delight of their 8 technical writers.

Automating the API Product Lifecycle

Pronovix

Looking at the full API Product Lifecycle, from defining an API and implementing the API, to launching with a solid developer site and experience, let’s see the newest tools - and potentially upcoming opportunities - to automate the creation of a solid developer experience. Creating a successful API requires a proper process from concept and design, through development, and into ongoing maintenance and responsive developer support. As developer expectations for better-quality APIs increase, tools have made it easier to implement this well. Thanks to standards like OpenAPIs, it’s easier to create a quality API, developer site, and overall experience. Many of us create API documentation or code libraries automatically from an OpenAPI spec, but there’s a lot more coming along to make our lives easier, and to make our APIs look better. In reviewing the full API Product Lifecycle to design an API people will use, let’s see the newest tools - and potentially upcoming opportunities - to better automate the creation of a compelling developer program.

GitHub as a Landing Page

Pronovix

Swagger for-your-api

Tony Tam

apidays LIVE New York 2021 - Designing API's: Less Data is More! by Damir Svr...

apidays

Tools and techniques for APIs

Jason Harmon

Swagger in the API Lifecycle

Ole Lensmar

Hidden Treasure - TestComplete Script Extensions

SmartBear

Introduction to NativeScript - BuildTruly Native Apps using JavaScript

Lohith Goudagere Nagaraj

Branching Your Way to Low-Code Perfection

OutSystems

API-first development

Vasco Veloso

The API-first design approach treats APIs as first-class citizens. The entire system or project is built around the idea that components connect via APIs. The first step is, therefore, to design the APIs and their connections. However, there is a gap between the beautiful world of API specifications and the reality of agile development. This gap means that published API specifications are often incomplete, missing examples or simply outdated. The API specification meant to help developers can be a thorn in one’s side because keeping the specification in sync with its implementation is a manual process, tedious and prone to be forgotten during the rush to deliver. We show how this gap can be bridged effectively using the API specification as the only source of truth driving the API implementation with proven tools enabling automation.

A guide to hiring a great developer to build your first app (redacted version)

Oursky

Hiring the right developer for your startup can be wearying. In this bitesized Garage Academy session, Ben Cheng, CEO of Oursky will provide you with all the tips for hiring your first developer -- from app development team structure to recruitment to management. About the speaker: Ben Cheng is the CEO of Oursky, a Hong Kong-based app dev studio that helps entrepreneurs and startups turn their ideas into reality. He has driven the company’s vision, strategy, and growth since its inception in 2008, and grown the technology-driven team from 3 to over 40 in Hong Kong and Taipei. ABOUT OURSKY: Founded in 2008, Oursky has developed web & mobile apps for startups and enterprises such as ASOS and Thomson Reuters. In 2015, 60% of Oursky's published iOS apps were featured in Apple's App Store and one was selected as a Best of 2013 App.

apidays LIVE Paris 2021 - Using OpenAPI to configure your API Gateway by Ole ...

apidays

Get Your Node.js API Swaggering with OpenAPI Spec

Adam Paxton

SPFx (SharePoint Framework)

Małgorzata Borzęcka

apidays LIVE Hong Kong 2021 - Less Data is More by Damir Svrtan, Netflix

apidays

Introducing OpenAPI Version 3.1

SmartBear

Getting Started with ASP.NET vNext

Lohith Goudagere Nagaraj

INTERFACE, by apidays - The 8 Key Components of a Modern API Stack by Iddo G...

apidays

API Conference 2021

José Haro Peralta

API integrations can be a pain. Anyone who has worked on API integrations has probably observed that, as a general rule, no API server survives first contact with the client. Reasons vary, from badly written API documentation to complete lack of API documentation. In this presentation, I want to address this problem by showing how developers can minimize the risk of API integration failures by using an approach called documentation-driven development. In documentation-driven development, we write the API specification first using a standard specification format. I'll show how we can leverage documentation to test and validate our API implementations before we release them. I'll show how we can use tools from the current ecosystem, such as Dredd, to automatically generate tests that validate our APIs.

What's hot

Engineer Stunning (API) documentation

Pronovix

Blood, sweat, and creating an API handbook

Pronovix

Let Writers Write: Automating the Boring Stuff for Our Docs Team

Pronovix

Automating the API Product Lifecycle

Pronovix

GitHub as a Landing Page

Pronovix

Swagger for-your-api

Tony Tam

apidays LIVE New York 2021 - Designing API's: Less Data is More! by Damir Svr...

apidays

Tools and techniques for APIs

Jason Harmon

Swagger in the API Lifecycle

Ole Lensmar

Hidden Treasure - TestComplete Script Extensions

SmartBear

Introduction to NativeScript - BuildTruly Native Apps using JavaScript

Lohith Goudagere Nagaraj

Branching Your Way to Low-Code Perfection

OutSystems

API-first development

Vasco Veloso

A guide to hiring a great developer to build your first app (redacted version)

Oursky

apidays LIVE Paris 2021 - Using OpenAPI to configure your API Gateway by Ole ...

apidays

Get Your Node.js API Swaggering with OpenAPI Spec

Adam Paxton

SPFx (SharePoint Framework)

Małgorzata Borzęcka

apidays LIVE Hong Kong 2021 - Less Data is More by Damir Svrtan, Netflix

apidays

Introducing OpenAPI Version 3.1

SmartBear

Getting Started with ASP.NET vNext

Lohith Goudagere Nagaraj

What's hot (20)

Engineer Stunning (API) documentation

Blood, sweat, and creating an API handbook

Let Writers Write: Automating the Boring Stuff for Our Docs Team

Automating the API Product Lifecycle

GitHub as a Landing Page

Swagger for-your-api

apidays LIVE New York 2021 - Designing API's: Less Data is More! by Damir Svr...

Tools and techniques for APIs

Swagger in the API Lifecycle

Hidden Treasure - TestComplete Script Extensions

Introduction to NativeScript - BuildTruly Native Apps using JavaScript

Branching Your Way to Low-Code Perfection

API-first development

A guide to hiring a great developer to build your first app (redacted version)

apidays LIVE Paris 2021 - Using OpenAPI to configure your API Gateway by Ole ...

Get Your Node.js API Swaggering with OpenAPI Spec

SPFx (SharePoint Framework)

apidays LIVE Hong Kong 2021 - Less Data is More by Damir Svrtan, Netflix

Introducing OpenAPI Version 3.1

Getting Started with ASP.NET vNext

Similar to Lessons Learned from Revamping Our Doc Site

INTERFACE, by apidays - The 8 Key Components of a Modern API Stack by Iddo G...

apidays

API Conference 2021

José Haro Peralta

Content Strategy and Developer Engagement for DevPortals

Axway

Introduction to The 6 Insights of API Practice (Bill Doerrfeld)

Nordic APIs

This is a session given by Bill Doerrfeld at Nordic APIs 2016 Platform Summit on October 25th, in Stockholm Sweden. Description: At Nordic APIs, our goal is to help businesses make smart tech decisions using APIs. To that end, via events and content Nordic APIs has treaded the business and technical sides to consider holistic best practices for providing an API. In this introductory Summit keynote talk, I’ll introduce what we’ve learned in the form of 6 core tenants of API practice which we’ve also designed this conference to address. Together they define a functional and evolving API: Platformification: Becoming an API-first company means undergoing a platformification process. This represents a global trend that many argue needs to be adopted to keep your business competitive within the digital economy. Strategy: Even before development begins, it’s important to consider your core API strategy. This is a defensible position that aligns your tech with platform goals, strategically exposing internal assets catered to an industry niche. Business Models: APIs have the power to improve efficiency, reduce overhead cost, open up complementary revenue streams, extend R&D, or even alter an existing business model entirely. Thus, you’ll want to determine the right monetization method that improves overall business and leads to end profitability. Security: With new major data breaches reaching the public ear every month, the importance of digital security can never be underestimated. For APIs, much of that lies in monitoring usage, access management, and identity control. Design: No developer wants to use an API with an ugly developer portal, unintuitive URL structures, outdated technology, or terrible lag time. In order to keep your developer consumer happy, paint the API portal and overall developer experience with an aesthetic brush. Marketing: In order to spark adoption, you need to have more than awesome functionality. I’ll review evangelism and discovery techniques you can use to get an API in the hands of more developer users. We’ll look at specific successful implementations of these philosophies in the wild, and mention examples from our blog and eBook content that have brought in industry experts to share their insights. I’ll initiate dialogue and open the conference up to see where we’re heading. What you can get out of embracing the core tenants of API practice?

Building a REST API for Longevity

MuleSoft

One of the greatest challenges to developing an API is ensuring that your API lasts. After all, you don’t want to have to release and manage multiple versions of your API just because you weren’t expecting users to use it a certain way, or because you didn’t anticipate far enough down the roadmap. In this session, we’ll talk about the challenge of API Longevity, as well as ways to increase your API lifecycle including having a proper mindset, careful design, agile user experience and prototyping, best design practices including hypermedia, and the challenge of maintaining persistence.

INTERFACE, by apidays - Building an Accessible API Spec

apidays

INTERFACE, by apidays - APIs: the next 10 years June 8, 9 & 10 2022 Building an Accessible API Spec with Traditional Engineering Teams Griffin Solot-Kehl, Developer Advocate at Dolby Laboratories ------------ Check out our conferences at https://www.apidays.global/ Do you want to sponsor or talk at one of our conferences? https://apidays.typeform.com/to/ILJeAaV8 Learn more on APIscene, the global media made by the community for the community: https://www.apiscene.io Explore the API ecosystem with the API Landscape: https://apilandscape.apiscene.io/ Deep dive into the API industry with our reports: https://www.apidays.global/industry-reports/ Subscribe to our global newsletter: https://apidays.typeform.com/to/i1MPEW

Documenting an API for the First Time? Quick-Start Tips for Your First API Do...

Petko Mikhailov

If the task to document an API comes earlier than the training and study you feel you need (and it always does!) and you don't know where to start and how to go about it, this presentation will show you not only how to survive your first API documentation gig but also how to turn it into a great learning experience and make a meaningful contribution at that. The presentation deals mainly with documenting REST APIs, but the approach and the conclusions apply to all kinds of APIs and their documentation. Presented at the tekom Spring Conference 2019 (Vienna).

Make Your Contribution Count. Adding Value to the API as a Technical Communic...

Petko Mikhailov

Even though documenting APIs is a highly technical proposition, the contribution that a technical communicator can make to the documentation is not the same as that of the writing developer. In fact, API documentation is the place where we can shine and make the difference between failure and success of a product on the market. In this presentation, we'll see what makes good API documentation and how API writers can bring unique value to it. Presented at the tekom Spring Conference 2019 (Vienna).

The API Lifecycle Series: Exploring Design-First and Code-First Approaches to...

SmartBear

apidays LIVE Paris 2021 - Lessons from the API Stewardship Journey in Azure b...

apidays

The Ultimate API Publisher's Guide

Pronovix

Always up to date, testable and maintainable documentation with OpenAPI

GOG.com dev team

Revamping Mailjet API documentation @ ParisAPI meetup

Mailjet

A Snapshot of API Design Trends In 2019

Bill Doerrfeld

Service api design validation & collaboration

Uchit Vyas ☁

apidays LIVE New York 2021 - Service API design validation by Uchit Vyas, KPMG

apidays

apidays LIVE Helsinki & North 2022_Building an Accessible API Spec with Tradi...

apidays

Introduction to the Art of API Practice

Bill Doerrfeld

Lessons learned on the Azure API Stewardship Journey.pptx

apidays

apidays LIVE Singapore 2022: Digitising at scale with APIs April 20 & 21, 2022 Lessons learned on the Azure API Stewardship Journey Adrian Hall, Principal Product Manager at Microsoft ------------ Check out our conferences at https://www.apidays.global/ Do you want to sponsor or talk at one of our conferences? https://apidays.typeform.com/to/ILJeAaV8 Learn more on APIscene, the global media made by the community for the community: https://www.apiscene.io Explore the API ecosystem with the API Landscape: https://apilandscape.apiscene.io/ Deep dive into the API industry with our reports: https://www.apidays.global/industry-reports/ Subscribe to our global newsletter: https://apidays.typeform.com/to/i1MPEW

Building the Eventbrite API Ecosystem

Mitch Colleran

Similar to Lessons Learned from Revamping Our Doc Site (20)

INTERFACE, by apidays - The 8 Key Components of a Modern API Stack by Iddo G...

API Conference 2021

Content Strategy and Developer Engagement for DevPortals

Introduction to The 6 Insights of API Practice (Bill Doerrfeld)

Building a REST API for Longevity

INTERFACE, by apidays - Building an Accessible API Spec

Documenting an API for the First Time? Quick-Start Tips for Your First API Do...

Make Your Contribution Count. Adding Value to the API as a Technical Communic...

The API Lifecycle Series: Exploring Design-First and Code-First Approaches to...

apidays LIVE Paris 2021 - Lessons from the API Stewardship Journey in Azure b...

The Ultimate API Publisher's Guide

Always up to date, testable and maintainable documentation with OpenAPI

Revamping Mailjet API documentation @ ParisAPI meetup

A Snapshot of API Design Trends In 2019

Service api design validation & collaboration

apidays LIVE New York 2021 - Service API design validation by Uchit Vyas, KPMG

apidays LIVE Helsinki & North 2022_Building an Accessible API Spec with Tradi...

Introduction to the Art of API Practice

Lessons learned on the Azure API Stewardship Journey.pptx

Building the Eventbrite API Ecosystem

More from Pronovix

By the time they're reading the docs, it's already too late

Pronovix

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

Pronovix

Success metrics when launching your first developer portal

Pronovix

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

Pronovix

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

Pronovix

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

Pronovix

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

Pronovix

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

Pronovix

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

Pronovix

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

Pronovix

Developing a best-in-class deprecation policy for your APIs

Pronovix

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

Pronovix

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?

Pronovix

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

Pronovix

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

Pronovix

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

Pronovix

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

Pronovix

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

Pronovix

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

Pronovix

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...

Pronovix

More from Pronovix (20)

By the time they're reading the docs, it's already too late

Optimizing Dev Portals with Analytics and Feedback

Success metrics when launching your first developer portal

Documentation, APIs & AI

Making sense of analytics for documentation pages

Feedback cycles and their role in improving overall developer experiences

GraphQL Isn't An Excuse To Stop Writing Docs

API Documentation For Web3

Why your API doesn’t solve my problem: A use case-driven API design

unREST among the docs

Developing a best-in-class deprecation policy for your APIs

Annotate, Automate & Educate: Driving generated OpenAPI docs to benefit everyone

What do developers do when it comes to understanding and using APIs?

Inclusive, Accessible Tech: Bias-Free Language in Code and Configurations

Creating API documentation for international communities

One Developer Portal to Document Them All

Docs-as-Code: Evolving the API Documentation Experience

Developer journey - make it easy for devs to love your product

Complexity is not complicatedness

How cognitive biases and ranking can foster an ineffective architecture and d...

Recently uploaded

UiPath Test Automation using UiPath Test Suite series, part 3

DianaGray10

Software Delivery At the Speed of AI: Inflectra Invests In AI-Powered Quality

Inflectra

In this insightful webinar, Inflectra explores how artificial intelligence (AI) is transforming software development and testing. Discover how AI-powered tools are revolutionizing every stage of the software development lifecycle (SDLC), from design and prototyping to testing, deployment, and monitoring. Learn about: • The Future of Testing: How AI is shifting testing towards verification, analysis, and higher-level skills, while reducing repetitive tasks. • Test Automation: How AI-powered test case generation, optimization, and self-healing tests are making testing more efficient and effective. • Visual Testing: Explore the emerging capabilities of AI in visual testing and how it's set to revolutionize UI verification. • Inflectra's AI Solutions: See demonstrations of Inflectra's cutting-edge AI tools like the ChatGPT plugin and Azure Open AI platform, designed to streamline your testing process. Whether you're a developer, tester, or QA professional, this webinar will give you valuable insights into how AI is shaping the future of software delivery.

How world-class product teams are winning in the AI era by CEO and Founder, P...

Product School

FIDO Alliance Osaka Seminar: FIDO Security Aspects.pdf

FIDO Alliance

"Impact of front-end architecture on development cost", Viktor Turskyi

Fwdays

I have heard many times that architecture is not important for the front-end. Also, many times I have seen how developers implement features on the front-end just following the standard rules for a framework and think that this is enough to successfully launch the project, and then the project fails. How to prevent this and what approach to choose? I have launched dozens of complex projects and during the talk we will analyze which approaches have worked for me and which have not.

GenAISummit 2024 May 28 Sri Ambati Keynote: AGI Belongs to The Community in O...

Sri Ambati

FIDO Alliance Osaka Seminar: Passkeys at Amazon.pdf

FIDO Alliance

Le nuove frontiere dell'AI nell'RPA con UiPath Autopilot™

UiPathCommunity

In questo evento online gratuito, organizzato dalla Community Italiana di UiPath, potrai esplorare le nuove funzionalità di Autopilot, il tool che integra l'Intelligenza Artificiale nei processi di sviluppo e utilizzo delle Automazioni. 📕 Vedremo insieme alcuni esempi dell'utilizzo di Autopilot in diversi tool della Suite UiPath: Autopilot per Studio Web Autopilot per Studio Autopilot per Apps Clipboard AI GenAI applicata alla Document Understanding 👨‍🏫👨‍💻 Speakers: Stefano Negro, UiPath MVPx3, RPA Tech Lead @ BSP Consultant Flavio Martinelli, UiPath MVP 2023, Technical Account Manager @UiPath Andrei Tasca, RPA Solutions Team Lead @NTT Data

Dev Dives: Train smarter, not harder – active learning and UiPath LLMs for do...

UiPathCommunity

💥 Speed, accuracy, and scaling – discover the superpowers of GenAI in action with UiPath Document Understanding and Communications Mining™: See how to accelerate model training and optimize model performance with active learning Learn about the latest enhancements to out-of-the-box document processing – with little to no training required Get an exclusive demo of the new family of UiPath LLMs – GenAI models specialized for processing different types of documents and messages This is a hands-on session specifically designed for automation developers and AI enthusiasts seeking to enhance their knowledge in leveraging the latest intelligent document processing capabilities offered by UiPath. Speakers: 👨‍🏫 Andras Palfi, Senior Product Manager, UiPath 👩‍🏫 Lenka Dulovicova, Product Program Manager, UiPath

Accelerate your Kubernetes clusters with Varnish Caching

Thijs Feryn

КАТЕРИНА АБЗЯТОВА «Ефективне планування тестування ключові аспекти та практ...

QADay

FIDO Alliance Osaka Seminar: Overview.pdf

FIDO Alliance

Bits & Pixels using AI for Good.........

Alison B. Lowndes

Unsubscribed: Combat Subscription Fatigue With a Membership Mentality by Head...

Product School

Quantum Computing: Current Landscape and the Future Role of APIs

Vlad Stirbu

Ransomware Mallox [EN].pdf

Overkill Security

The infamous Mallox is the digital Robin Hoods of our time, except they steal from everyone and give to themselves. Since mid-2021, they've been playing hide and seek with unsecured Microsoft SQL servers, encrypting data, and then graciously offering to give it back for a modest Bitcoin donation. Mallox decided to go shopping for new malware toys, adding the Remcos RAT, BatCloak, and a sprinkle of Metasploit to their collection. They're now playing a game of "Catch me if you can" with antivirus software, using their FUD obfuscator packers to turn their ransomware into the digital equivalent of a ninja. ------- This document provides a analysis of the Target Company ransomware group, also known as Smallpox, which has been rapidly evolving since its first identification in June 2021. The analysis delves into various aspects of the group's operations, including its distinctive practice of appending targeted organizations' names to encrypted files, the evolution of its encryption algorithms, and its tactics for establishing persistence and evading defenses. The insights gained from this analysis are crucial for informing defense strategies and enhancing preparedness against such evolving cyber threats.

De-mystifying Zero to One: Design Informed Techniques for Greenfield Innovati...

Product School

Transcript: Selling digital books in 2024: Insights from industry leaders - T...

BookNet Canada

The publishing industry has been selling digital audiobooks and ebooks for over a decade and has found its groove. What’s changed? What has stayed the same? Where do we go from here? Join a group of leading sales peers from across the industry for a conversation about the lessons learned since the popularization of digital books, best practices, digital book supply chain management, and more. Link to video recording: https://bnctechforum.ca/sessions/selling-digital-books-in-2024-insights-from-industry-leaders/ Presented by BookNet Canada on May 28, 2024, with support from the Department of Canadian Heritage.

Future Visions: Predictions to Guide and Time Tech Innovation, Peter Udo Diehl

Peter Udo Diehl

I'm excited to share my latest predictions on how AI, robotics, and other technological advancements will reshape industries in the coming years. The slides explore the exponential growth of computational power, the future of AI and robotics, and their profound impact on various sectors. Why this matters: The success of new products and investments hinges on precise timing and foresight into emerging categories. This deck equips founders, VCs, and industry leaders with insights to align future products with upcoming tech developments. These insights enhance the ability to forecast industry trends, improve market timing, and predict competitor actions. Highlights: ▪ Exponential Growth in Compute: How $1000 will soon buy the computational power of a human brain ▪ Scaling of AI Models: The journey towards beyond human-scale models and intelligent edge computing ▪ Transformative Technologies: From advanced robotics and brain interfaces to automated healthcare and beyond ▪ Future of Work: How automation will redefine jobs and economic structures by 2040 With so many predictions presented here, some will inevitably be wrong or mistimed, especially with potential external disruptions. For instance, a conflict in Taiwan could severely impact global semiconductor production, affecting compute costs and related advancements. Nonetheless, these slides are intended to guide intuition on future technological trends.

Neuro-symbolic is not enough, we need neuro-*semantic*

Frank van Harmelen

Neuro-symbolic (NeSy) AI is on the rise. However, simply machine learning on just any symbolic structure is not sufficient to really harvest the gains of NeSy. These will only be gained when the symbolic structures have an actual semantics. I give an operational definition of semantics as “predictable inference”. All of this illustrated with link prediction over knowledge graphs, but the argument is general.

Recently uploaded (20)

UiPath Test Automation using UiPath Test Suite series, part 3

Software Delivery At the Speed of AI: Inflectra Invests In AI-Powered Quality

How world-class product teams are winning in the AI era by CEO and Founder, P...

FIDO Alliance Osaka Seminar: FIDO Security Aspects.pdf

"Impact of front-end architecture on development cost", Viktor Turskyi

GenAISummit 2024 May 28 Sri Ambati Keynote: AGI Belongs to The Community in O...

FIDO Alliance Osaka Seminar: Passkeys at Amazon.pdf

Le nuove frontiere dell'AI nell'RPA con UiPath Autopilot™

Dev Dives: Train smarter, not harder – active learning and UiPath LLMs for do...

Accelerate your Kubernetes clusters with Varnish Caching

КАТЕРИНА АБЗЯТОВА «Ефективне планування тестування ключові аспекти та практ...

FIDO Alliance Osaka Seminar: Overview.pdf

Bits & Pixels using AI for Good.........

Unsubscribed: Combat Subscription Fatigue With a Membership Mentality by Head...

Quantum Computing: Current Landscape and the Future Role of APIs

Ransomware Mallox [EN].pdf

De-mystifying Zero to One: Design Informed Techniques for Greenfield Innovati...

Transcript: Selling digital books in 2024: Insights from industry leaders - T...

Future Visions: Predictions to Guide and Time Tech Innovation, Peter Udo Diehl

Neuro-symbolic is not enough, we need neuro-*semantic*

Lessons Learned from Revamping Our Doc Site

1. Lessons learned from revamping our doc site API Days, Paris December, 2019 Ilona Koren-Deutsch Prabhjot Singh

2. Prabhjot Singh • Engineering the Twitch API • More comfortable with Golang than French • Still plays games written in the 90s

3. Ilona Koren-Deutsch ● Technical Documentation Manager ● Trained chef and former academic ● Really bad at Super Smash Bros

4. Needs Analysis If your API is the product, the documentation is the user interface.

5. Squad Goals ● Increased user satisfaction ● Fewer (and shorter) calls for support ● More people using our APIs ● More and better mods and extensions

6. Mods and Extensions • Create ways for viewers and streamers to interact • Offer special offers, content, or in-game items to Twitch viewers • Let streamers to show off what mods they are playing to their community so they can download and play the mod with their favorite streamer

7. Important factors in an API

8. API doc must include: ● Authentication ● Status codes ● Error messages ● Sample code ● Terms of use ● Changelog

9. Models for excellent developer portals The 2019 DevPortal Awards winners: • Best API Reference Documentation: Adyen API Explorer • Best New DX Innovation: NBG Technology Hub • Best Onboarding: Nexmo Developer • Best Accessible DevPortal: Barclays API Exchange

10. Best in Show API docs ● TomTom Developer Portal ● Quali Community ● Genesys PureCloud Developer Center ● Stripe ● Heroku ● Twilio

11. Issues with the current API docs • Difﬁcult CMS • Enormous amount of engineering time • Code that devs can’t copy-and-paste • Feedback in too many places • Dev forums • Discord • Informal

12. Why OpenAPI is cool

13. OpenAPI “The ability of APIs to describe their own structure is the root of all awesomeness in OpenAPI. “

14. OpenAPI Allows you to describe your entire API, including: ● Available endpoints and operations on each endpoint ● Operation parameters ● Authentication methods ● Contact information, license, terms of use and other information

15. Solves our problems ● Comprehensive API Documentation ● Easy Auto-Generation ● Automates Contract Testing ● Can build Mock APIs

16. Planning

17. Planning • Explore pain-points with the existing documentation process • Examine industry practices to set goals for our docs • Evaluate OpenAPI Spec as the source of truth and collaboration for our docs • Share opinions around different workﬂows and reach an agreement around the process for collaborating over, creating and maintaining docs

18. Tools

19. Demo Results

20.

21.

22.

23.

24. Live Results

25. Stay tuned! /dev.twitch.tv/docs/

26. Twitch is hiring! www.twitch.tv/jobs/

27.

28. Prabhjot: singhfqp@twitch.tv (Twitch: mangotreebird) Ilona: korendeu@twitch.tv (Twitch: cycene) (Discord: cycene)

29. Reference Mermade/widdershins https://github.com/Mermade/widdershins Slate Docs https://github.com/slatedocs/slate