In 2022 we will have 5 API The Docs Virtual events, you can already sign up for the sessions. Currently we are finalising the program, detailed agenda is coming soon.

API The Docs Events in 2022

26 October

Emese Hallgató (Pronovix) - 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."

William Bishop (Miro) - Developing a best-in-class deprecation policy for your APIs

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

Melissa Mahoney, John Williams (MongoDB) - Annotate, Automate, & Educate: Driving generated OpenAPI documentation 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."

9 November

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

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

Jessie Mongeon - API Documentation For Web3

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

Akshay Bhalotia - 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?"

16 November

Mary Kate Comer - Making Removing Unconscious Bias Unconscious with a Linter

"Unconscious bias comes in many forms like the language we use in day to day conversations or the "in-speak" and jargon of different companies, industries, specialties, and groups. If you take a look at language, you may be surprised to find some common terms and phrases ableist, gendered, or born out of race. In this talk, Mary Kate Comer will share a linter she developed to help curb the use of that language, to be applied to writing documents or code. From the obvious "white list" v "black list" or the terms "master" and "slave" which are common in engineering, to some that you just might not think about. Not only does this linter provide helpful alternatives and suggestions, it can be customized by each organization, to learn and grow it's inclusive word banks. This helps not only with documentation, but can also be used as a learning tool to support change in how we speak to each other. "

Roy Derks - GraphQL Isn't An Excuse To Stop Writing Docs

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

Past events:

21 September

Christoph Weber - 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. Once a company decides to fully manage and document their APIs, put emphasis on an API-first strategy, and streamline digital governance, they start looking for a developer portal that can support their needs. 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. "

Josef Zeman - 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."

Peter S. Look - Docs-as-Code: Evolving the API Documentation Experience

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

This talk presents what problems we solved or will solve by taking a ""docs-as-code"" approach to producing API documentation. Not only will the solutions be summarized, but trade-offs will also be shared."

12 October

Alec Clews - Creating API documentation for international communities

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

Arthur Garcia - Make it Easier to Release Release Notes

"When sending release notes on a piece that’s gone into production with 100 different services, screens, and teams, how do you let people know what is in the delivery? You could collect the information on all the builds and documentation, compile it and then publish... Or you could automate the process using a simple extension. In this talk, Art Garcia will share with you the development and use of the extension to make releasing release notes easier by generating a wikipage, and the security tooling workarounds you may need to use depending on your companies’ security practices. "

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

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

Our sponsors: