Learn how to scale beyond old choices and find the next big thing for your API documentation. This talk will use the past, present, and future of Marqeta’s docs to provide a framework for growing and evolving your own.
Advancing Your API Strategy in an Infrastructure WorldPronovix
You can lead a horse to water, but you can’t make it drink. This is an accurate summary of what my initial journey of evangelizing API usage was like. In this talk I will take the audience through our journey, what worked, what didn’t work and what we learned along the way.
Many of us have heard about Docs As Code. Applying the same tooling and delivery CI/CD (Continuous Integration and Continuous Delivery) pipelines as developers to improve the quality of (API) documentation sounds nifty. We’ll take a look at the philosophy, best practices and how to get started.
Lessons Learned from Revamping Our Doc SitePronovix
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.
Your Developer Portal is the primary interface that developers will have with your company’s product. So what does your developer portal say about you? We’ll share what we’ve learned at BigCommerce about redesigning a developer portal that helps your developers–and your company–meet their goals.
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.
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
My opening keynote for the 2016 Nordic APIs Platform Summit held in Stockholm, Sweden. In it I describe the 6 Insights that guide Nordic APIs content and events, including API Platforms, API Strategy, API Business Models, API Strategy, API Design, API Security, and API Marketing.
Let Writers Write: Automating the Boring Stuff for Our Docs TeamPronovix
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.
Advancing Your API Strategy in an Infrastructure WorldPronovix
You can lead a horse to water, but you can’t make it drink. This is an accurate summary of what my initial journey of evangelizing API usage was like. In this talk I will take the audience through our journey, what worked, what didn’t work and what we learned along the way.
Many of us have heard about Docs As Code. Applying the same tooling and delivery CI/CD (Continuous Integration and Continuous Delivery) pipelines as developers to improve the quality of (API) documentation sounds nifty. We’ll take a look at the philosophy, best practices and how to get started.
Lessons Learned from Revamping Our Doc SitePronovix
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.
Your Developer Portal is the primary interface that developers will have with your company’s product. So what does your developer portal say about you? We’ll share what we’ve learned at BigCommerce about redesigning a developer portal that helps your developers–and your company–meet their goals.
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.
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
My opening keynote for the 2016 Nordic APIs Platform Summit held in Stockholm, Sweden. In it I describe the 6 Insights that guide Nordic APIs content and events, including API Platforms, API Strategy, API Business Models, API Strategy, API Design, API Security, and API Marketing.
Let Writers Write: Automating the Boring Stuff for Our Docs TeamPronovix
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.
An overview of devportal technologies and their (dis)advantagesPronovix
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
The UX of DX: User Testing in the Invisible World of APIsPronovix
As anyone who has tried to call certain endpoints knows, being RESTful isn’t the only requirement to making your API product easy to use. Developers are people too and as DX experts we owe them the same UX testing we do with our front-end products.
Pure APIs: Development workflows for successful API integrationsJosé Haro Peralta
APIs are the fundamental tenets of the Internet. They enable integrations between different services, and they power the servers that bring our applications to life. API integrations lay at the core of our API-driven world, and delivering successful API integrations is fundamental to sustain it. However, more often than not, API integrations tend to fail due to ineffective development workflows. In this presentation, I want to present various API development workflows that have helped me and my clients deliver successful API integrations. I’ll show how documentation-driven development, using mock servers, robust API testing frameworks, and API visibility tools can help to significantly reduce the chances of API integration failure and to keep errors under control.
apidays LIVE Paris 2021 - Using OpenAPI to configure your API Gateway by Ole ...apidays
apidays LIVE Paris 2021 - APIs and the Future of Software
December 7, 8 & 9, 2021
Using OpenAPI to configure your API Gateway
Ole Lensmar, CTO at Kubeshop
Blood, sweat, and creating an API handbookPronovix
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.
apidays LIVE Paris 2021 - Why GraphQL is Perfect For Microservices by Roy Der...apidays
apidays LIVE Paris 2021 - APIs and the Future of Software
December 7, 8 & 9, 2021
Why GraphQL is Perfect For Microservices
Roy Derks, Developer Relations at Stepzen
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.
A Starters Guide to Building APIs with JavascriptAll Things Open
Presented by: Tom Wilson, hyper63
Presented at the All Things Open Virtual Meetup
Abstract: APIs (Application Program Interfaces) is how programs can talk with other programs and is a design consideration for many products. Let’s discuss: Why you should build an application with an API? What are the top 5 requirements of designing an API with examples? Some open-source javascript frameworks that can help you design and build your API.
In order to get the most out of this talk, you should have a good understanding of http REST protocol and general application development. Familiarity with javascript and technologies like NodeJS and Express would be a plus.
In this talk, you should come away with a good understanding of why you should consider building an API in your application, key good practices every API should include, and how you could implement an API using Javascript.
apidays LIVE New York 2021 - Designing API's: Less Data is More! by Damir Svr...apidays
apidays LIVE New York 2021 - API-driven Regulations for Finance, Insurance, and Healthcare
July 28 & 29, 2021
Designing API's: Less Data is More!
Damir Svrtan, Senior Software Engineer at Netflix
Eight Hours to API Literacy: A Fast, Fun On-ramp for WritersPronovix
Writers are experts at dealing with ambiguity. We do highly technical work, frequently without formal CS education. We find ways to make content out of wireframes, code strings, Jira tickets, and spit. We especially fall back on these skills when documenting APIs, where the information is often scarce and our understanding of the APIs and how they’re used can feel abstracted from the product. But APIs aren’t just for reference anymore. With an update to our New Relic developer site in the works, we needed to up our game. In February, we hired Chris Cowell to teach members of the Tech Docs and UX teams REST API basics. The class was a huge success because it covered the topics we needed to learn, but also because Chris created a lively, interactive, accessible experience. Even those of us who have been documenting APIs for years came away with deeper understanding and greater confidence.
In this talk, Chris Cowell and Michelle Fredette discuss high- and low-level knowledge gaps the training addressed, and how the class has enriched our docs and UX work, as well as our relationships with SMEs. We’ll share some basic tips and finally, we’ll talk about how classes like this one—which a participant called, “the single most effective technical training I’ve ever received”—are fundamental to the expanding complexity of our careers.
Lessons learned: Choosing your documentation systemPronovix
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.
apidays LIVE New York 2021 - Why Software Teams Struggle with API Security Te...apidays
apidays LIVE New York 2021 - API-driven Regulations for Finance, Insurance, and Healthcare
July 28 & 29, 2021
Why Software Teams Struggle with API Security Testing
Scott Gerlach, Co-Founder & Chief Security Officer at StackHawk
apidays LIVE New York 2021 - API tool chain for low budget programs by Paul K...apidays
apidays LIVE New York 2021 - API-driven Regulations for Finance, Insurance, and Healthcare
July 28 & 29, 2021
API tool chain for low budget programs
Paul Krajewski, Sr. Integration Engineer at Dina Care
To view the recording of this webinar please use the below URL:
http://wso2.com/library/webinars/2015/03/wso2-product-release-webinar-wso2-app-factory-2.1.0/
In this webinar, Manjula Rathnayaka, associate technical lead, and Kasun De Silva, software engineer at WSO2, will present the following new features and improvements to App Factory 2.1:
Adding new application types by including an archive
Ability to add runtime externally
Puppet scripts for App Factory deployments
WSO2 BAM integration for user activity
Custom URL improvements
[API World 2021 ] - Understanding Cloud Native DeploymentWSO2
Microservices and APIs built for digital transformation products require agile, reliable, and scalable cloud native infrastructure to truly meet customer expectations for a great "always there" user experience. Whether deployed on-premises or hosted in a public cloud, understanding and leveraging the right approach is key to success. This session takes up where the development process leaves off, tracking the standardization of containers and container orchestration for automated deployment, including current and future platform trends WSO2 and others are following.
Beyond the basic Swagger UI: Adyen API ExplorerAleksei Akimov
OpenAPI/Swagger has rapidly become the next standard in the world of API documentation. But Swagger UI, used by most API portals, is far from ideal. At Adyen we reimagined Swagger implementation resulting in a new API Explorer; and this is my talk at API The Docs Amsterdam, where I shared the lessons learnt by our team.
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...Tom Johnson
This is a presentation I gave to the Southwestern Ontario STC chapter on API documentation on Feb 2, 2015. For more details, see my blog at http://idratherbewriting.com. You can listen to the recorded presentation here: http://youtu.be/I8rGe2w1sAo.
Why we chose Argo Workflow to scale DevOps at InVisionNebulaworks
As the DevOps team grows in size and start to form a multi DevOps team structure, it starts to experience growing pains such as working in silos, decreased velocity, or lack of collaboration. The solution is to standardize tools for automation and provide the building blocks of commonly used patterns readily available. This is where workflows come into play. Adopting Workflows provides a common scalable platform for DevOps engineers to automate, trigger, and execute repetitive tasks and therefore leads to increased efficiency and innovation.
An overview of devportal technologies and their (dis)advantagesPronovix
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
The UX of DX: User Testing in the Invisible World of APIsPronovix
As anyone who has tried to call certain endpoints knows, being RESTful isn’t the only requirement to making your API product easy to use. Developers are people too and as DX experts we owe them the same UX testing we do with our front-end products.
Pure APIs: Development workflows for successful API integrationsJosé Haro Peralta
APIs are the fundamental tenets of the Internet. They enable integrations between different services, and they power the servers that bring our applications to life. API integrations lay at the core of our API-driven world, and delivering successful API integrations is fundamental to sustain it. However, more often than not, API integrations tend to fail due to ineffective development workflows. In this presentation, I want to present various API development workflows that have helped me and my clients deliver successful API integrations. I’ll show how documentation-driven development, using mock servers, robust API testing frameworks, and API visibility tools can help to significantly reduce the chances of API integration failure and to keep errors under control.
apidays LIVE Paris 2021 - Using OpenAPI to configure your API Gateway by Ole ...apidays
apidays LIVE Paris 2021 - APIs and the Future of Software
December 7, 8 & 9, 2021
Using OpenAPI to configure your API Gateway
Ole Lensmar, CTO at Kubeshop
Blood, sweat, and creating an API handbookPronovix
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.
apidays LIVE Paris 2021 - Why GraphQL is Perfect For Microservices by Roy Der...apidays
apidays LIVE Paris 2021 - APIs and the Future of Software
December 7, 8 & 9, 2021
Why GraphQL is Perfect For Microservices
Roy Derks, Developer Relations at Stepzen
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.
A Starters Guide to Building APIs with JavascriptAll Things Open
Presented by: Tom Wilson, hyper63
Presented at the All Things Open Virtual Meetup
Abstract: APIs (Application Program Interfaces) is how programs can talk with other programs and is a design consideration for many products. Let’s discuss: Why you should build an application with an API? What are the top 5 requirements of designing an API with examples? Some open-source javascript frameworks that can help you design and build your API.
In order to get the most out of this talk, you should have a good understanding of http REST protocol and general application development. Familiarity with javascript and technologies like NodeJS and Express would be a plus.
In this talk, you should come away with a good understanding of why you should consider building an API in your application, key good practices every API should include, and how you could implement an API using Javascript.
apidays LIVE New York 2021 - Designing API's: Less Data is More! by Damir Svr...apidays
apidays LIVE New York 2021 - API-driven Regulations for Finance, Insurance, and Healthcare
July 28 & 29, 2021
Designing API's: Less Data is More!
Damir Svrtan, Senior Software Engineer at Netflix
Eight Hours to API Literacy: A Fast, Fun On-ramp for WritersPronovix
Writers are experts at dealing with ambiguity. We do highly technical work, frequently without formal CS education. We find ways to make content out of wireframes, code strings, Jira tickets, and spit. We especially fall back on these skills when documenting APIs, where the information is often scarce and our understanding of the APIs and how they’re used can feel abstracted from the product. But APIs aren’t just for reference anymore. With an update to our New Relic developer site in the works, we needed to up our game. In February, we hired Chris Cowell to teach members of the Tech Docs and UX teams REST API basics. The class was a huge success because it covered the topics we needed to learn, but also because Chris created a lively, interactive, accessible experience. Even those of us who have been documenting APIs for years came away with deeper understanding and greater confidence.
In this talk, Chris Cowell and Michelle Fredette discuss high- and low-level knowledge gaps the training addressed, and how the class has enriched our docs and UX work, as well as our relationships with SMEs. We’ll share some basic tips and finally, we’ll talk about how classes like this one—which a participant called, “the single most effective technical training I’ve ever received”—are fundamental to the expanding complexity of our careers.
Lessons learned: Choosing your documentation systemPronovix
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.
apidays LIVE New York 2021 - Why Software Teams Struggle with API Security Te...apidays
apidays LIVE New York 2021 - API-driven Regulations for Finance, Insurance, and Healthcare
July 28 & 29, 2021
Why Software Teams Struggle with API Security Testing
Scott Gerlach, Co-Founder & Chief Security Officer at StackHawk
apidays LIVE New York 2021 - API tool chain for low budget programs by Paul K...apidays
apidays LIVE New York 2021 - API-driven Regulations for Finance, Insurance, and Healthcare
July 28 & 29, 2021
API tool chain for low budget programs
Paul Krajewski, Sr. Integration Engineer at Dina Care
To view the recording of this webinar please use the below URL:
http://wso2.com/library/webinars/2015/03/wso2-product-release-webinar-wso2-app-factory-2.1.0/
In this webinar, Manjula Rathnayaka, associate technical lead, and Kasun De Silva, software engineer at WSO2, will present the following new features and improvements to App Factory 2.1:
Adding new application types by including an archive
Ability to add runtime externally
Puppet scripts for App Factory deployments
WSO2 BAM integration for user activity
Custom URL improvements
[API World 2021 ] - Understanding Cloud Native DeploymentWSO2
Microservices and APIs built for digital transformation products require agile, reliable, and scalable cloud native infrastructure to truly meet customer expectations for a great "always there" user experience. Whether deployed on-premises or hosted in a public cloud, understanding and leveraging the right approach is key to success. This session takes up where the development process leaves off, tracking the standardization of containers and container orchestration for automated deployment, including current and future platform trends WSO2 and others are following.
Beyond the basic Swagger UI: Adyen API ExplorerAleksei Akimov
OpenAPI/Swagger has rapidly become the next standard in the world of API documentation. But Swagger UI, used by most API portals, is far from ideal. At Adyen we reimagined Swagger implementation resulting in a new API Explorer; and this is my talk at API The Docs Amsterdam, where I shared the lessons learnt by our team.
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...Tom Johnson
This is a presentation I gave to the Southwestern Ontario STC chapter on API documentation on Feb 2, 2015. For more details, see my blog at http://idratherbewriting.com. You can listen to the recorded presentation here: http://youtu.be/I8rGe2w1sAo.
Why we chose Argo Workflow to scale DevOps at InVisionNebulaworks
As the DevOps team grows in size and start to form a multi DevOps team structure, it starts to experience growing pains such as working in silos, decreased velocity, or lack of collaboration. The solution is to standardize tools for automation and provide the building blocks of commonly used patterns readily available. This is where workflows come into play. Adopting Workflows provides a common scalable platform for DevOps engineers to automate, trigger, and execute repetitive tasks and therefore leads to increased efficiency and innovation.
Web development tools have gone through a series of major changes than how they used to be. For starters, we no longer need computers the size of refrigerators to make introductory web runners.
Thanks to the power of pall computing (and a bevy of great SaaS businesses), we frequently do not indeed need a necessary computer at all. From the most introductory web cyber-surfer, you can do everything from edit query to sluice the rearmost videotape games.
In this session, Massimo will go through the Swagger specification and some open source tools built on top of Swagger. This includes Swagger editors and how they can be used to create our API stubs,
the Swashbuckle tool to auto-generate swagger.json, to keep it in sync with the server code and to make it discoverable. Finally he will demonstrate the Swagger integration in the API Management space (Azure API Management and Sentinet).
Codit presents the slide deck of the presentation on Swagger, given by Massimo Crippa (Codit) on Integration Monday.
In this session, Massimo did go through the Swagger specification and some open source tools built on top of Swagger. This included Swagger editors and how they can be used to create our API stubs, the Swashbuckle tool to auto-generate swagger.json, to keep it in sync with the server code and to make it discoverable. Finally he demonstrated the Swagger integration in the API Management space (Azure API Management and Sentinet).
Github Copilot vs Amazon CodeWhisperer for Java developers at JCON 2023Vadym Kazulkin
In this talk I will compare 2 services Github Copilot (including Copilot X) and Amazon CodeWhisperer from the perspective of the Java developers in terms of the quality of the given recommendations for simple tasks, complex algorithms, Spring Boot and AWS development, IDE integration and pricing.
Both services are the machine learning-powered services that help improve developer productivity by generating code recommendations based on developers’ comments in natural language and their code. Based on natural language comments, these services also automatically recommend unit test code that matches your implementation code.
Documentation An Engineering Problem UnsolvedSchalk Cronjé
Following on from an idea of Dan Allan, this explores desires for authoring documentation from an engineering point of view. THhe second half looks at how Asciidoctor project is trying to address some of these desoires.
Building an Open Source iOS app: lessons learnedWojciech Koszek
Building an Open Source iOS app: lessons learned
Dec 12, 2016, Hacker Dojo (Santa Clara), 6pm
In this talk I'm going to talk about lessons learned from building Sensorama (http://www.sensorama.org), an Open Source sensor platform for data science. The main theme of the talk will be Open Source: what is great about it, what is bad and how you must become a part of the Open Source community to really move quickly and benefit from it. For this project, I did both the code and the design, so you'll have a chance to see how solo-developer deals with time/feature constraints, which tools I've used and what my approach towards development in this mode is. In other words: I'll tell you what I did to stay sane. If the iOS development were a walk in a dark city park, this talk may turn out to be your flashlight. If you like it, star it at GitHub: https://github.com/wkoszek/sensorama-ios
Agenda
https://www.meetup.com/svmobiledev/events/235836893/
Materials
https://github.com/wkoszek/talks/tree/master/svmobiledev2016
Some links from the slides
Fake it till you make it presentation https://developer.apple.com/videos/play/wwdc2014/223
Designing for Future Hardware https://developer.apple.com/videos/play/wwdc2015/801/
References
WWW: http://www.sensorama.org
GitHub (code): https://github.com/wkoszek/sensorama-ios
GitHub (artwork): https://github.com/wkoszek/sensorama-artwork
Author
WWW: http://www.koszek.com
Twitter: https://twitter.com/wkoszek
LinkedIn: https://www.linkedin.com/in/wkoszek/
Email: wojciech (at) koszek.com
This half-day tutorial introduces Protocol Buffers, gRPC, and the open source tools that Google uses to publish and support some of the world's biggest APIs. We'll show how the Protocol Buffer language allows APIs to be described, reviewed, and implemented in a programming-language independent way, how gRPC enables high-performance streaming APIs, and how \ a few simple conventions can enable related tools to serve robust REST APIs and generate production-quality client libraries in seven popular programming languages. This is API publishing the Google way, but large teams aren't required. With shared open-source tooling, even the smallest developer can build scalable, usable APIs that delight.
https://apistrat18.sched.com/event/FTR3/usable-apis-at-scale-with-protocol-buffers-and-grpc-tim-burks-andrew-gunsch-google
Content Strategy and Developer Engagement for DevPortalsAxway
Slides from Write the Docs Ottawa Meet Up at Shopify HQ in Canada, June 24, 2019
We’ll walk through 5 scenarios and concrete ways of reaching a developer community for frictionless and increased engagement.
Some technologies are tools of the DevOps trade. Chef, Jenkins, Vagrant and Zookeeper are all tools that can be used for huge leverage and impact by the right people. Rarely, however, is there a technology that *enables* the practice of DevOps. The advent of the cloud and disposable infrastructure is one example. Docker is in this second, more rarified class.
Containers, Serverless, Polyglot Development World, And Others…10 trends resh...PROIDEA
During this presentation, you will learn about the 10 changes that might reshape the developer tools market in the next 10 years. Jarek will discuss containers, serverless functions, and how it all supports an agile and CI/CD experience. The move to a polyglot development world means most applications will be written in a mix of languages, with developers favoring tools that help them navigate easily between languages. Jarek will also walk us through the evolution away from stand-alone developer workstations toward cloud-and-container based development environments offered as a service.
DocOps: Documentation at the Speed of AgileMary Connor
Presented at Keep Austin Agile 2016: How to we make documentation "Agile", given the Agile Manifesto? How do you get into the Definition of Done? What does "DocOps" mean, in the simplest and broadest terms? What should your requirements be for a DocOps transformation, and how do you find a tool stack that fits them? Where do you start, and how do you escape a waterfall reengineering of your legacy docs?
By the time they're reading the docs, it's already too latePronovix
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 FeedbackPronovix
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 portalPronovix
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.
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 pagesPronovix
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 experiencesPronovix
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 DocsPronovix
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.
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 designPronovix
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.
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 APIsPronovix
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.
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 ConfigurationsPronovix
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 communitiesPronovix
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.
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 ExperiencePronovix
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 productPronovix
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.
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
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
Accelerate your Kubernetes clusters with Varnish CachingThijs Feryn
A presentation about the usage and availability of Varnish on Kubernetes. This talk explores the capabilities of Varnish caching and shows how to use the Varnish Helm chart to deploy it to Kubernetes.
This presentation was delivered at K8SUG Singapore. See https://feryn.eu/presentations/accelerate-your-kubernetes-clusters-with-varnish-caching-k8sug-singapore-28-2024 for more details.
UiPath Test Automation using UiPath Test Suite series, part 3DianaGray10
Welcome to UiPath Test Automation using UiPath Test Suite series part 3. In this session, we will cover desktop automation along with UI automation.
Topics covered:
UI automation Introduction,
UI automation Sample
Desktop automation flow
Pradeep Chinnala, Senior Consultant Automation Developer @WonderBotz and UiPath MVP
Deepak Rai, Automation Practice Lead, Boundaryless Group and UiPath MVP
Connector Corner: Automate dynamic content and events by pushing a buttonDianaGray10
Here is something new! In our next Connector Corner webinar, we will demonstrate how you can use a single workflow to:
Create a campaign using Mailchimp with merge tags/fields
Send an interactive Slack channel message (using buttons)
Have the message received by managers and peers along with a test email for review
But there’s more:
In a second workflow supporting the same use case, you’ll see:
Your campaign sent to target colleagues for approval
If the “Approve” button is clicked, a Jira/Zendesk ticket is created for the marketing design team
But—if the “Reject” button is pushed, colleagues will be alerted via Slack message
Join us to learn more about this new, human-in-the-loop capability, brought to you by Integration Service connectors.
And...
Speakers:
Akshay Agnihotri, Product Manager
Charlie Greenberg, Host
Software Delivery At the Speed of AI: Inflectra Invests In AI-Powered QualityInflectra
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.
Kubernetes & AI - Beauty and the Beast !?! @KCD Istanbul 2024Tobias Schneck
As AI technology is pushing into IT I was wondering myself, as an “infrastructure container kubernetes guy”, how get this fancy AI technology get managed from an infrastructure operational view? Is it possible to apply our lovely cloud native principals as well? What benefit’s both technologies could bring to each other?
Let me take this questions and provide you a short journey through existing deployment models and use cases for AI software. On practical examples, we discuss what cloud/on-premise strategy we may need for applying it to our own infrastructure to get it to work from an enterprise perspective. I want to give an overview about infrastructure requirements and technologies, what could be beneficial or limiting your AI use cases in an enterprise environment. An interactive Demo will give you some insides, what approaches I got already working for real.
Future Visions: Predictions to Guide and Time Tech Innovation, Peter Udo DiehlPeter 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.
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.
JMeter webinar - integration with InfluxDB and GrafanaRTTS
Watch this recorded webinar about real-time monitoring of application performance. See how to integrate Apache JMeter, the open-source leader in performance testing, with InfluxDB, the open-source time-series database, and Grafana, the open-source analytics and visualization application.
In this webinar, we will review the benefits of leveraging InfluxDB and Grafana when executing load tests and demonstrate how these tools are used to visualize performance metrics.
Length: 30 minutes
Session Overview
-------------------------------------------
During this webinar, we will cover the following topics while demonstrating the integrations of JMeter, InfluxDB and Grafana:
- What out-of-the-box solutions are available for real-time monitoring JMeter tests?
- What are the benefits of integrating InfluxDB and Grafana into the load testing stack?
- Which features are provided by Grafana?
- Demonstration of InfluxDB and Grafana using a practice web application
To view the webinar recording, go to:
https://www.rttsweb.com/jmeter-integration-webinar
КАТЕРИНА АБЗЯТОВА «Ефективне планування тестування ключові аспекти та практ...QADay
Lviv Direction QADay 2024 (Professional Development)
КАТЕРИНА АБЗЯТОВА
«Ефективне планування тестування ключові аспекти та практичні поради»
https://linktr.ee/qadayua
GraphRAG is All You need? LLM & Knowledge GraphGuy Korland
Guy Korland, CEO and Co-founder of FalkorDB, will review two articles on the integration of language models with knowledge graphs.
1. Unifying Large Language Models and Knowledge Graphs: A Roadmap.
https://arxiv.org/abs/2306.08302
2. Microsoft Research's GraphRAG paper and a review paper on various uses of knowledge graphs:
https://www.microsoft.com/en-us/research/blog/graphrag-unlocking-llm-discovery-on-narrative-private-data/
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.
Let's dive deeper into the world of ODC! Ricardo Alves (OutSystems) will join us to tell all about the new Data Fabric. After that, Sezen de Bruijn (OutSystems) will get into the details on how to best design a sturdy architecture within ODC.
20. Know the history.
● Ask who wrote the original docs.
● Ask who built the original tools.
● Keep a record of the docs history.
● Use tools like archive.org to take a look back.
24. Do you:
● Create fragile processes to cover tool gaps?
● Worry about overwriting unpublished work?
● Avoid certain docs because the tool is too difficult?
● Prefer writing docs outside your tool?
25. Watch for signs of trouble.
● Avoid bad processes meant to cover tool gaps.
● Avoid needing to work outside your tool.
● Track unintended or undesirable outcomes.
28. What resources do our developers need?
PaymentsCompetency
Technical Competency
★
Required competency for success
Your awesome
platform goes here
Your developers
(usually)
start here
29. What resources do our developers need?
PaymentsCompetency
Technical Competency
★
API Reference (2016)
30. What resources do our developers need?
PaymentsCompetency
Technical Competency
★
API Reference (2016)
DevGuides(2017)
31. What resources do our developers need?
PaymentsCompetency
Technical Competency
★
API Reference (2016)
DevGuides(2017)
Tutorials (2018)
32. What resources do our developers need?
PaymentsCompetency
Technical Competency
★
API Reference (2016)
DevGuides(2017)
Tutorials (2018)
PaymentsBasics
SDKs (2019)
33. Simple but powerful authoring
Move docs closer to the code
Prepare for automated tools
Keep the source portable
An existing ecosystem
34. Go beyond pain points.
● What could you do with a new tool? Dream big!
● Create a shared taxonomy describing your docs.
● Communicate!
● Demonstrate the added value with a prototype.
48. GitHub
A git host for
version control
Visual Studio Code
A text editor
49. GitHub
A git host for
version control
Visual Studio Code
A text editor
50.
51.
52. Humans can read the source.
#2
#1
#3
There’s a healthy ecosystem.
It can live near your code.
53.
54. Humans can read the source.
#2
#1
#3
#4
There’s a healthy ecosystem.
It can live near your code.
It’s convertible and portable.
55.
56. Humans can read the source.
#2
#1
#3
#4
#5
There’s a healthy ecosystem.
It can live near your code.
It’s convertible and portable.
It’s free and you own your content.
57. Build your own prototype.
● Limit risk by putting your plan into action early.
● Give yourself time to find and reject the wrong tools.
● Keep in mind any third-party content policies.
● Use tools like Stackbit and Netlify to try SSGs.
62. Use the transition to practice.
● Document your tool using your tool.
● Start a dedicated Slack channel.
● Test your new publishing process.
● Run user testing, too!
65. AsciiDoc-based toolchain
+ Extensible & testable
+ Standards-based
- Assembly required
Content management system
+ Easy to use
- Vendor-based ($$$)
- Monolithic and bulky
is here!
Gatsby
Static site
generator
AsciiDoc
Markup
syntax
GitHub
Version
control
Drone
CI/CD
66. API spec-based toolchain
+ Automates multiple outputs
+ Source of truth = code = docs
- Organizational buy-in required
AsciiDoc-based toolchain
+ Extensible & testable
+ Standards-based
- Assembly required
Content management system
+ Easy to use
- Vendor-based ($$$)
- Monolithic and bulky
is here!
OpenAPI
API spec
Your API
Docs + code samples
SDKs, Postman, etc.
Gatsby
Static site
generator
AsciiDoc
Markup
syntax
GitHub
Version
control
Drone
CI/CD
67. Be thoughtful about the
long-term writing experience
and information architecture.
69. Plan for the future.
● Choose tools that can grow and adapt with you.
● Don’t over-invest in any one tool or format.
● Build in phases toward your end goal.
● Keep dreaming up the next big improvements!
70. Your giant leap toolkit
1. Know the history of your docs site, tool, and team.
2. Track any signs that you’re digging yourself into a hole.
3. Go beyond pain points to show added value.
4. Build your own prototype.
5. Use the transition to practice.
6. Plan for the future to make your next leap easier.