API THE DOCS, CHICAGO
One-day conference about API documentation and developer portals. Explore the latest best practices, strategies and new trends.
April 8th, 2019



(Re)designing a Developer Portal that your developers will want to use

Karen White

Developer advocate at BigCommerce

“It is the story of our developer portal evolving in parallel with the way that we think about developer experience as a company.”

In order to become the world’s most opened SaaS platform

  • Have an API first mindset.
  • Find a way to provide a kind of flexibility to your developers.
  • Provide a place where developers can find resources and support.
  • Do interviews with the developers to find pain points.
  • Discover your portal through the users’ eyes.

AAARRP framework by Phil Leggetter

Awareness, Acquisition, Activation, Retention, Revenue, Referral, Product is a popular way of describing user journeys and all the supporting activities that developers go through as they use your product.

Creating developer personas: gather data, analyze, validate.

Maturity model in the devportal journey

  • Level 1: closed system where users might not be able do an API call and email for support
  • Level 2: introducing some amount of self-service functionality
  • Level 3: including many of the components of a successful devportal: docs in multiple programming languages, code samples, active community
  • Level 4: having all those things plus having a certain level of personalization (experience appropriate for certain roles)

A Developer Portal Scorecard helps you find out where your program is in the maturity model right now and what you should focus on more.

Measuring success

  • No single metric can tell you how healthy your devportal is.
  • It’s important to understand the goals and which user behavior supports those goals.
  • You need to establish a baseline for comparison with enough reliable data.
  • Decide which user behaviour you can actually measure.
  • Changing behavior takes time.

Takeaways

  • A devportal is more than just a place to stick your documentation.
  • "You can’t do it all right now - and that’s okay" : align your efforts with your company’s priorities.
  • Be aware that partner managers, the product team and the leadership team are also interested in your devportal.
  • Changing user behavior takes time and you need the support of your internal stakeholders.

Talk Summary

Karen's slides



Karen's presentation

Devportal Information Architecture: a 4-step method

Mónika Alföldi-Zörgő

Information Architect and Content Writer at Pronovix

Pronovix developed a 4-step information architecture method to help their clients identify all the individual pieces of content for their developer portal and to find out how these pieces are related.

The high-level goals behind the method

  • Create a resilient system.
  • Provide a lens to guide thinking and planning.
  • Get to know what and why.
  • Provide a great customer experience.
  • Realize a content first approach.

Not all devportals are the same: specific requirements and business goals of companies have a significant impact on their devportals.

The method consists of four steps, where each step is built on the results of the previous ones.

1. Website Architecture Analysis Interview with questions grouped around four main topics:

  • Devportal site goals
  • Target audience
  • Competition
  • Inspiration sites

Main deliverable: proto personas.

2. Inventory Session

  • Review and make an inventory of all the existing materials the client has.
  • Get a clear understanding of the technical background of the project, any problems or glitches of the current system, expectations.

Main deliverable: inventory list with four groups of content (existing content, inspirational sites, results of the website analysis discussion, suggested elements based on the interviews).

3. The Information Architecture Workshop

Exercises based on the results from the first two sessions:

  • Persona validation
  • Element collection
  • Element sorting
  • Group naming
  • Sitemap creation
  • Storyboards
  • User journeys
  • Sitemap for the MVP

4. Defining Next Steps

Check each page of the MVP sitemap closely and identify the content layout.

Add high-level estimates to 3 areas:

  • Content: What content goes on there? Does that exist? Do we need a template?
  • UX and UI Design: page layout and brand needs.
  • Development: frontend and backend related tasks.

Talk summary

Mónika's slides



Mónika's presentation

One Size Still Doesn't Fit All

Amara Graham

Senior Developer Advocate at IBM

“Our content as it exists is really kind of that XXL t-shirt — everyone could wear it but probably just wouldn’t be comfortable with it — could we do things to change our existing content so that even the developers that need the finest clarity get it, and they’d feel comfortable, they’d feel confident, they’d want to continue using our product and they’d want to continue to be in this space.”

Think about the different backgrounds or needs of your different users: General assumptions about an enterprise developer

  • Well supported, budgeted, sensitized to make things work.
  • You can easily get to know their skills, the technical background they work with.
  • Being a developer is their day job.

General assumptions about a game developer

  • It is a fluid definition.
  • You don’t know their skill set or what they are comfortable with.
  • Being a developer is their day job, second job, hobby or passion project.

Nights and weekend developers

  • Try to make sure that docs and tutorials will make sense to them as well.
  • Enable them to build something with AI.

What are the things that need to be considered to set up all those developers for success?

  • Give them "confidence building exercises".
  • Give them examples with the bare minimum of code.
  • Show them how to use these services together.
  • Show them just the exact way how to authenticate.
  • Show the exact way how to enter an API key.
  • Tell them why they would use things like cURL.

Things to think about

  • Who is using your docs today? Are they getting what they need?
  • Are you agile? Consider adjusting your personas too.
  • Did you cover the basics? Are you sure?
  • Did you make assumptions that could alienate groups?

Talk Summary

Amara's slides



Amara's presentation

The UX of DX: User Testing in the Invisible World of APIs

Jenny Wanger

Product manager at SpotHero

Goal: improve API usability by applying UX methods to APIs.

Discovery: Build something useful

  • Who is actually going to use this?
  • Collaborate with your end user to develop use cases.
  • Determine what information to include that solves for their need.
  • Techniques: interviews, site visits, ethnography.

Taxonomy: Make it easy to navigate

  • Think of navigation and how the personas might apply in terms of what an individual is looking for.
  • Use user personas to create different journeys for your developers.
  • Focus on method and resource names, order of operations.
  • Techniques: card sorting, tree testing.

Mock & Prototype: Get the structures right

  • Think through the structure of the API request and response body.
  • The goal is to get a basic outline of each endpoint.
  • Techniques: paper prototypes, instant messenger APIs.

Usability: Find perfection

  • Mock up your API in full detail without backend.
  • Follow UX usability testing techniques to run testing.
  • This is where you decide on the fine details.
  • Techniques: usability testing via Postman and Swagger.

Takeaways

  • Don’t let an already built API stop you from building the right API.
  • Creating documentation for really poorly designed APIs is a lot harder than just getting the API right at the first place.
  • Following the UX framework a really fantastic API can be designed within two weeks.

Talk Summary

Jenny's slides



Jenny's presentation

Gateways to Gateways: API Development in the Cloud

Amy Arambulo Negrette

Cloud Software Engineer Lead at Cloudreach

Containers

Containers are streamlined, lightweight virtual machines, without the need to upskill API developers.

  • An API (its framework, its dependencies, and a webserver) can live in the container, which can be moved from machine to machine.
  • The required infrastructure of the API (Linux or Windows machine) remains outside.
  • Be aware of high overhead on container maintenance: one bad container could do a lot of harm.

Serverless

Serverless architecture uses Cloud Native services to create an infrastructure that does not need to be managed by the developer.

  • This is often a combination of a cloud provided API gateway and functions as a service of containers.
  • Cloud native and cloud optimized : for developing APIs, the cloud provider will create a collection of endpoints that connects to a cloud compute service triggered by events such as HTTP requests or event queues.
  • Pay-as-you-go.
  • It is a very different programming paradigm which requires complex documentation, uses vendor lock and where developers touch more infrastructure.

Legacy APIs

  • Fewer code changes, less amount of initial work, fastest to live and needs no upskilling.
  • It is very expensive (pay per hour) and you will lose optimization.

Modernized APIs

  • Optimized and future proof.
  • Slow to market, language specific and require overhaul of infrastructure and software.

Netflix API gateway model concept (Zuul, 2014)

  • Allows multiple video clients such as a Roku, SmartTv, Smart Phone, Laptop, etc. to connect to a Netflix user and streaming services using a single API gateway connecting to a service layer.
  • Zuul works because the workflow for all clients is the same, also allowing front-end optimization.
  • Ase-specific: one cannot send any number of different requests at a single endpoint and infer where it should go depending on the content without previous development for that logic.

Things to consider when you start building a very large API project

  • Frequency and size of requests are still important.
  • How similar are the requests?
  • How many endpoints/resources will you have?
  • How is this better than different APIs?
  • APIs can do a lot, but they shouldn’t do everything.

Talk summary

Amy's slides



Amy's presentation

Case Study: Integration and automation create delightful API docs

Jenifer Schlotfeldt

Content Experience Architect at IBM Cloud

How to generate a great authoring experience?

  • Get consistency.
  • Enable content writers to collaborate with developers.
  • Make sure the API is good.

Goals:

  • Provide one place where customers can find all the API Docs available for the 190 services IBM Cloud has.

Support developers and writers

  • Using API specs (Swagger 2.0; now OpenAPI 3.0).
  • Creating non-method front matter and editing descriptions and examples.
  • Collaborative authoring with SMEs.

Improve speed, quality, and compliance

  • Decrease time from feature release to documentation and SDK support,
  • Avoid copy-and-paste and other errors from hand-written SDKs and API docs,
  • Improve and enforce the agreement among the API definition, the API docs, and the SDKs,
  • Swagger is great for a spec, but it doesn’t provide all the additional docs and content you need to understand.

Metrics and quality (for both descriptions and API Docs)

  • Automated test cases reported on IBM’s Content Quality Dashboard
  • Acrolinx for API Docs too
  • Linters with the specs
  • OpenAPI validator
  • Links and Markdown quality tested

Workflows: Open API spec is the single source of truth

DevOps: develop, validate, build, deliver.

ContentOps: author, build, validate, deliver.

API reference output: organization, definition details, and examples.

Components for authoring

  • Markdown: the front matter (non-method) content:
    • Manually creating Markdown with attributes (or generate from templates),
    • Open-source Markdown generator for the IBM Cloud,
  • OpenAPI definition + extensions: generate request example syntax, enable or hide features and methods,
  • JSON “blob” (from SDK generator): the SDK method info, all the “middle pane” content for the SDKs.

Talk summary

Jenifer's slides



Jenifer's presentation

From Zero to Sixty: Driving a DocOps Based Approach to APIs at Ford Motor Company

Darren Shelcusky

Manager Platform Enablement at Ford Motor Company

Ford as an API company The mission is to design, build, grow and invest in new mobility services. Mobility services require an ecosystem built around APIs.

Ford is an API driven company: data analytics, city solutions, autonomy, FinTech, fleet services, location services, predictive systems, charging networks, parking, smart ownership, ride sharing, vehicle history, telematics, infotainment.

Why is Ford doing DocOps?

  • Complete and accurate documentation, and the product’s visibility has a great value in API decision making.
  • Good developer experience is based on content - CX (customer experience) is the most important determinant of success or failure.
  • Agile practices can be in opposition with good docs so Agile might need a reality check:
  1. individuals and interactions vs. rocesses and tools,
  2. working product vs. comprehensive documentation,
  3. customer collaboration vs. ontract negotiation,
  4. responding to change vs. ollowing a plan.

Ford Mobility approach to DocOps

  • Conducting an API scavenger hunt: to understand at what stage is the API product right now.
  • Exposing hidden factories: get to know what is really going on behind the scenes, what developers do to get their jobs done, reveal and eliminate pain points.
  • Changing the view on what is content: besides static documentation there is real time and dynamic documentation.

DocOps practices must encompass all content types

  • Expose APIs with meaningful metrics.
  • Enable self-service API onboarding.
  • Provide meaningful developer assistance.

Takeaways

  • DocOps practices are transformational changes - change management is key.
  • Change only occurs when product teams work together.
  • Don’t just focus on static content.

Talk summary

Darren's slides



Darren's presentation

Making Great Documentation: Seven Steps that Go Beyond Autogeneration

Robert Delwood

Lead API Documentation Writer at iManage

What CEOs see: a small group of writers can support a large group of programmers, and they only hire just enough writers along with automation to be able to produce a minimum set of documentation.

Writing great documentation

  • Automation is very good for writing average documentation.
  • Automation is fine if your product is as simple as Petstore.
  • Developers and techwriters might have different writing skills.

What about writing great documentation? Installing 100% confidence 100% of the time.

Document types

  • API reference is the icon of the industry - unfortunately they’re not enough.
  • API refs are like a dictionary, not a novel.
  • For a good novel, you also need getting started, tutorials, snippets and examples and quick reference guide.

How we use APIs?

  • Conventional (compiled)
  • REST (HTTP)

You’re never done writing

  • Review constantly.
  • You’re going to learn more each day, so add that material.
  • Go back in a week, month, or three months and review the material.
  • See it through the eyes of someone reading it for the first time.

If it’s not already broken, then break it

  • Your tool is broken if it doesn’t do exactly what you want it to do.
  • Yes, for writer’s that’s every tool we have.
  • Complain about it to manufacturers, and to forums.
  • It’s the only way we’re going to get change.

Takeaways

  • cURL is not programming: it’s a testing tool, and not even the best one.
  • Examples are everything: make examples copy and paste, place them prominently, don’t vary the examples.
  • Automation is sometimes like a bad translation: they lost us from the start.
  • Software developers who write the docs would be ideal, but are hard to find.

Talk summary

Read Robert's article about his talk.

Sauntering Beyond Swagger with Open Source Tools

Jessica Parsons

Documentation engineer at Netlify

About Swagger & OAS

  • Single source of truth for API development: the glue that connects all the different parts.
  • Can be generated from code (or generated from the content in the code).
  • Even if we talk about automation, there’s still somebody behind it.
  • Can be used to generate SDKs and docs.
  • Swagger spec tooling - Swagger Editor, Swagger Inspector, Swagger UI, Swagger Codegen.

Sauntering in the direction of

  • Better process: spec-driven development
  • Better customer UX: improved site design
  • Better writer UX: GUI file editor

Maintaining tech values

  • Decoupled & modular
  • Prebuilt, portable markup
  • Open source where possible

Site Generators

  • LucyBot Docgen has OS demo version,
  • MrinDoc/RapiDoc (fully OS) generates straight from the OAS and builds the UI in JavaScript,
  • ReDoc: generates responsive 3-column API docs,
  • Slate, Shins and Widdershins: build the site from Markdown, so you have to convert the OpenAPI to Markdown.

GUI editing

  • Netlify CMS works with data stored in files with Git, geared for OS contribution, file-based config.
  • OpenAPI spec documents are not simple data files:
    • heavily nested,
    • are often really long,
    • have limited modularity,
    • patterned fields are user-defined.

Other options

Talk summary

Jessica's slides



Jessica's presentation

The Inverted Funnel of Developer Documentation

Bob Watson, PhD

Assistant Professor at Mercer University

The conversion funnel

  1. Awareness
  2. Interest
  3. Desire
  4. Action

Documentation’s inverted funnel

  1. A landing page or portal to attract customers
  2. Hello World app(s) to get them interested
  3. Tutorials – to show how your product can solve their problem
  4. Reference content – which makes up the foundation of the pyramid

Reference topics make your customers smarter

  • Reference topics help to fill the gaps in the customer’s journey and they help carry the customer across the finish line.
  • Reference topics are the most valuable - developers spend the most time in docs.

Success metrics

  • One size doesn’t fit all.
  • Sign ups and Hello Worlds show who’s been converted.
  • API usage (API keys, API calls) shows who’s been successful.
  • Monitoring individual page performance identifies problems.
  • Reference topic analytics indicate usage and value.

Takeaways

  • Remember that your customer’s are probably different.
  • Know your customer’s journey.
  • Be where developers need you.
  • Automate as much as possible, but don’t abandon the human touch.
  • Remember that less is more in case of reference docs
  • Make your authoring tools work for you.
  • Track the analytics that matter.

Read Bob Watson’s article about his talk.

Talk summary

Bob's slides



Bob's presentation

Write Your Docs like Nobody Reads Them

Shy Ruparel

Developer Evangelist at Contentful

What to do when nobody reads your docs?

RTFM (Read the Fancy Manual) can be harmful: “Not only am I not going to help you, but also I want to make sure that you feel ashamed about your inability to help yourself.”

Four ways of learning Documentation is only one of the tools used to educate people on how to use the product. You can support different ways of learning by providing the right form of documentation.

  • Writing learners are the perfect target for traditional documentation: they can get the most value out of written documentation.
  • Visual learners want to visualize what can be done and how: take advantage of charts, gifs, video tutorials.
  • Auditory learners learn by hearing things: podcasts and recordings are best for them.
  • Kinesthetic learners are experimental learners: poke around things to get to know them.

Areas of documentation Developer docs break down into three different levels:

  1. Strategic: content operations, content modeling architecture
  2. Technical: practitioner guides, developer guides
  3. Reference: API & SDK docs

Content & Documentation discovery When the documentation is too big to explore, reducing friction around information discovery is important.

  • Consider the needs of developers with different backgrounds.
  • Optimize content for user behavior.
  • Find out what people do to get to your website.
  • Build internal search into the documentation.

More than text Documentation doesn’t need to be only static content:

  • interactive UI (try-out options, Execute buttons, Postman),
  • copy / paste ready samples,
  • video content (difficult to maintain).

Takeaways

  • Don’t be afraid to delete content when it gets stale.
  • Evolve your documentation by logging where people struggle.
  • Stack Overflow and Slack are great places for developers to find answers.
  • Link back to your own documentation when you answer a question.
  • Spend time with your community in person.

Talk summary

Shy's slides



Shy's presentation

Original recording of the conference by Kristof Van Tomme, Creative Commons Attribution Share-Alike License v3.0

Conference sponsors:

MongoDB logo

SlashData logo

Netlify logo