API The Docs Virtual 2022

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:

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

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

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

26 October

To be announced.

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

To be announced.

Our sponsors: