With great pleasure we share with you the recordings, slide decks and our notes from API The Docs in Amsterdam 2019 October. A big shout-out to the presenters: THANK YOU!
Product Owner and API Evangelist at ABN AMRO
"We need to move from an egosystem to an ecosystem. [...] Empower internal and external developers to build the future of banking on top of APIs."
To get there is a couple of marathons.
A/ Cultural and organizational change:you need an API-first mindset and the processes and best practices for the teams in place, where documentation is important.
B/ The APIs must be:
"How is someone else going to use my service beyond what I can expect that they are going to use it for?"
Developer advocate at NexmoDev
How and why to bring over your team's docs knowledge to the Github pages.
If users look for docs at the source, aka the code repo, they may never see your devportal.
For this reason, bring the landing page experience into the Github docs. Landing pages bring context to orient users, they should have a similar experience with the Github docs.
Opensourced Nexmo docs standards.
Readme file's content gets rendered on many pages differently and this can be used to advantage.
Every project needs name, purpose, scope, link to docs, license, how to get help.
"More info in a readme is great, your developer audience will find their way through."
Readme "furniture": use headings and a table of contents to help users navigate longer readme text.
License field: add exact, opensource approved license. Many people filter search results on license too.
Add contribution guide, code of conduct. In certain situations you do not need contributions: write explicitly what contribution you find useful.
Further reading links.
Lorna explains why having a good readme on your GitHub repositories is more than just good practice here at @APItheDocs Amsterdam!— Jaap Brasser (@Jaap_Brasser) 10 October 2019
Thanks for sharing your insights @lornajane!#ApiDocs #ApiTheDocs pic.twitter.com/an7B5t3KSq
DevRel Product Manager at Marqeta
When a good tool doesn't fit your needs anymore.
Marqeta's problem: multiple writers creating and updating lots of docs at the same time in a marketing CMS.
Finding and solving the pain points with existing tools is maybe not enough forever. Scaling may require better tools.
Warning signs may be:
Track unintended or undesirable outcomes of a tool-change:
Can work towards:
When method searching, go beyond existing pain points:
Marqeta's new toolchain: Gatsby-ASCIIDoc-GitHub-Drone.
Future plan: OpenAPI spec-based toolchain. Pro: automates multiple outputs, singe source of truth. Contra: organizational buy-in required.
DocOps Engineer at Pronovix
Building, maintaining, continually improve your (API) documentation using docs-as-code the DocOps way.
Test for the quality of documentation! All aspects of API documentation:
Understanding what is good writing. Typo-free doesn’t mean it’s good.
Test first for:
Using the same tooling for documentation as coding also means:
Benefits of docs-as-code setup:
Need deeper knowledge of engineering tools, workflows, solid base understanding of security.
Tests are working - trust the results.
Developers, devOps, site reliability (SRE) teams help design good tests.
Content strategy and test design:
Content analytics, automated testing, deploying (publishing)
Write - test- share
Quality Assurance benefits:
What you want to achieve:
Check on accessibility and performance of site over time, always improve (Lighthouse) QA with CI/CD
.@der_sven_ on engineering stunning API documentation, by extending your editor with plugins, by automating tests, and leveraging Docs As Code, at #APItheDocs:— Floor Drees #MSOpenHack (@FloorDrees) 10 October 2019
Understanding of git and version control, as well as security and permissions are required for adopting Docs as Code. pic.twitter.com/Qb8GeDuU6V
Developer Advocate at Rubrik, Inc.
API landscape challenges:
1. beginner technical user:
2. experienced technical user:
3. Non-Technical Stakeholder:
Open-sourced the docs to get feedback, with quick start guides. Unexpected input, also marketing department started using it.
Organized and standardized their GitHub repo:
Advice: standardize and automate unit tests to speed up, especially for a very active project.
Developer Advocate at AmadeusITGroup
Doubt will cost you potential customers. Be transparent and clear about what you have.
It has to take less than a minute's reading to understand what is your core business.
Make the references interactive, parameters can be set ready for copy-and-paste, keep always up to date.
Onboarding: easy and fast!
Sign-up is only for tryout, you can ask questions later. Rule of thumb advice: 30 seconds to understand your API, 0 seconds to create an account and 3 minutes to first API call.
A later email validation should give valuable information: hand-holding and inspiration.
You can easily give a free trial with a limited test data set.
Payment: as you go, transparent model with alternative paths.
Support: clear support channels, public platform for techies, FAQ. Set up monitoring.
Summary: make it easy, be transparent and focus on DX. Hire a devrel.
Strategy, Program Manager at Amadeus for Developers
User feedback is absolutely instrumental in getting to a great DX:
User interviews: uncover common needs and frustrations. Target customers, scripted, no leading questions.
Prototyping: move from concept to building, fix bugs early on.
Usability tests to observe how people use your APIs:
Goal: how to make your docs easy to find and easy to use, the first API call fast.
Index cards on taxonomy: validate your assumptions on associations.
Beta-testing is the moment of truth. Production ready apps, in-depth review, inconsistencies and performance issues found. Can be a small internal & external audience. It is a lot of effort to create and maintain a beta-testers' community. Always have the technical resources available for what you are promising.
Survey, metrics, support: ascertain the health of your APIs.
Open support channels: 75% of users would report issues if there is a channel.
Hackathons: direct observation options, answer support questions, team interviews, surveys. Follow-up with participants and beta-testers can bring the true deep insights.
Customers' frustrations are your compass.
Assuming "Open API" means "public" might not translate to your developers Maria Garcia #apithedocs— manil Canada ~/. API the Docs, Amsterdam (@keywordnew) 10 October 2019
Yep. My trio came up with 3 different first impressions of the prompt "Open API". pic.twitter.com/wxa8IJTorq
Director at Griffiths Waite
Product Owner at Atradius
The Atradius API Portal details can unfortunately only be shared to the wider public once the portal is formally released. It is currently in beta. Release was originally scheduled for September '19 but the launch was postponed to November '19. Atradius emailed their apologies for not being able to share publicly.
talk proposal summary
Lead Technical Writer at Salesforce
Product Owner at Salesforce
Currently 23+ REST APIs, 10 authoring tool chains, 175+ writers, 10 doc portals.
Challenges: multi-version support, localization, differing release schedules, limited codebase access for so many writers. Hundreds of scrum teams.
Need: a spec-agnostic authoring and publishing solution that fits 175+ writers, minimize context-switch.
Agreed Goal: unified automation pipeline for engineers, simple process and toolchain for writers, 1 amazing API portal for customers.
Changes for productivity started as grassroots efforts from writers:
Friends of docs:
engineering teams generate API spec from code
writers and DocOps update docs
developer marketing team publishes the docs to a customer portal
Results in one round proposal for change: 1. high-level requirements + 2. technical proposal + 3. user-stories
Obstacles to mind:
Separate out the docs from the API spec file by a parser, so updates are easier for writers. Notifications for writers about new tickets for writing needs automated.
Developer Advocate at AmadeusITGroup
Why do you need API governance? Because of the massive amount of information moving.
Lots of different people designing and maintaining APIs in the company.
Regulation is necessary to keep these APIs reliable.
API governance within Amadeus is:
Amadeus' HAPPY principle:
API template fields:
Phases of API creation and review:
Architect at Stoplight.io
What tooling supports Open API v3.0?
Design first or code first?
code first, generate docs: slow feedback loop, customer feedback comes after the docs (putting docs in with code, theoretically mostly right and evolving)
design first, ditch for code first
design first, evolve with code: design with OpenAPI, mocks and docs, get customer feedback. Use open API files to simplify code, deploy code and docs. New functionality requested: repeat.
Stoplight developed an editor to work well writing APIs. How/when do we create documentation? Create mocks? Their solution is Studio
Keep code and docs in sync: rendering of description files, use them to simplify the code, involve the developers in this.
Enforcing style guides.
Consistent APIs save you time and money.
Product Designer at Shopify
How do users understand the problem space?
Discussions can be difficult because words often hold many different definitions. Diagrams, models or a glossary could help ensure a better alignment.
In analyzing past decisions and other companies' decisions, you must consider the context of these decisions. The context may have changed since then.
When interviewing: no leading questions!
Use visual representations to map out your concept in a complex ecosystem.
Tree-testing is a good way to check a GraphQL schema with users. Eg. it showed that the logic Shopify devs thought of was working, but also showed that users found another route to the same answer.
Oversimplification can ultimately complicate things! Avoid conflating similar but separate concepts, it could cause problems when scaling.
To avoid lengthy debates on terminology you can create a glossary and work on the logic, agree to work out the precise terminology later. Because naming things is hard.
Balance between your product vision and users' feedback.