A track that focuses on the latest best practices, strategies and new trends relevant to API documentation and developer portals. 10th December 2019.
With great pleasure, we share with you the recordings, presentation slides and our recaps from APIdays, API The Docs Track in Paris 2019 December. A big Thank you to all the speakers!
Founder & CEO at APIMatic.io
How many developers are using your developer portal?
If the answer is an awkward silence, maybe it is because the developer needs to write code before they can create their first ‘Hello World’ using the API.
Today, developers are the connection between APIs and the outside world where APIs are independent mediums between platform- and language-specific devices.
You need to treat APIs as a product, and if you do so, care for the user (developer) experience. Make the developer achieve her/his goal in the least number of steps and amount of time.
How can you help them access and use your APIs more easily?
Don’t make them code (anything extra).
Let them focus on what they are building.
Docs & DX track kicked off with Ali talking about how SDK creates phenomenal developer experience.
Developer Advocate at Rubrik Inc.
Backup is traditionally not an innovative space because of legacy tooling or custom tools/modules.
The goal of building the SDKs:
Simplify the API interaction:
Interactive use: Supporting multiple languages, simplified and more human-readable data output.
Extensibility: Ease of updating, Build tooling on SDK, Extend SDK based on the requirements of the tools with the help of a feedback loop.
Additional goals: SDKs are Open source, Unit tests, Documentation.
API SDK Development – Lessons Learned
Jaap was presenting what he learnt from API SDK development at Rubrik.
UX Lead at Ad Hoc LLC
If an API design considers the needs of developers (DX) and focuses on engineering aspects and technical needs only, it has zero connection to end users. This leads to a cycle of creating data that only suits the needs of the task at hand.
“We should strive to end users’ needs to be able to build data-rich applications that serve end user needs alongside the business requirements.”
Human-centered design (HCD) focuses on the overall usability of the product and accessibility for a particular userbase (personas). The most important metric to measure the success of an API program is usage.
How problem-solving is done with the HCD Life Cycle:
HCD provides a new concept and way of working that will get designers and developers closer to the data and the interfaces that interact with the data.
Use API data and architecture in the process:
Human-centered design identifies what information the end user will look for when using the application. With this knowledge, APIs can be built to convey the most relevant data.
Co-Founder & CEO at Pronovix
Can we combine biotechnology and devportals/digital transformation?
What is digital transformation aside from being a buzzword?
Enterprise companies are adaptive and rigid. To become more adaptive, we need more learning surface with customers.
One goal, many transformations: Agile transformation, DevOps, Self-organizing teams, InnerSourcing, APIs.
Digital transformation is changing the architecture of the world and of how business works. It has increased our interconnection and interdependence.
Two major results:
“Through your developer community a devportal can help you tune your company for complex adaptive behavior.”
Patterns for complex adaptivity: 5 properties of adjustment to become a complex adaptive system (CAS).
Product Manager at Microsoft Azure API Management
The first step when building developer portals for customers is to conduct extensive research to plan and design before development.
The 6 principles that lead technical decisions:
Technical Documentation Manager at Twitch
Software Developer at Twitch
“If your API is the product, the documentation is the user interface.”
Identify what makes good documentation and make sure that everything is available and searchable.
Issues with the current documentation:
Taking a design-first documentation approach, OpenAPI can solve our problems as it allows you to describe your entire API (endpoints, operation parameters, authentication, contact information).
Planning to use OpenAPI for the Twitch APIs encourages developers and tech writers to work together.
Tools: We go from OpenAPI Spec through a translator that transforms the docs to be digestible.
The generated documentation provides:
Founder at CompliancePal
What happens when agile development meets with regulated environments?
Medical software documentation has to comply with:
Modern agile development is based on 2-4 week long sprints. By the end of this period the development team ships a fully functional product.
Where does the documentation fit in?
Typically, the development phase is followed by a documentation phase where the now fixed configurations are documented for different audiences. Deployment can happen once this is done.
In reality, if the documentation has to change as frequently as the code, you need an automatic method to keep the documentation always up-to-date.
You can use an augmented GitHub workflow that makes it possible for developers and for compliance officers to achieve a continuous seamless experience through APIs. You must start using this method from the beginning of the development, and do it with each commit.
Find the real use of documentation. And do it for real, not by obligation.
Automated compliance and documentation by @VladStirbu at #apidays
Developer Evangelist at Twilio Inc.
To support the developers effective use of your APIs you need to equip them with the information they need. Documentation is one of the ways to achieve this goal.
Try to balance different kinds of documentation types for maximized impact.
Never forget: people will use or not use your products based on their experience.
Focus on answering these questions:
Address your documentation to each of them: use variety and balance.
Personalize your documentation to your audience. You have to take measures to decide what you should focus on:
Front-end Engineer Lead at BCaster
Arch Conveyer/Community Manager at Code Afrique
A documentation pattern that takes into consideration the constant changes/improvements in code and business logic needs to be reflected internally for every closed sprint.
If your documentation is unable to catch-up with the changes, you’ll achieve an unsynchronized knowledge-base.
You have to communicate with someone you don't know. If you cannot pass information to users, your documentation is not communicating.
Do your developers write the documentation? Do you have a dedicated team for that? How do you handle your documentation?
What should you improve?
Share your useful practices with the community.
Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.