API THE DOCS, CHICAGO

(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

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

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

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

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

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

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

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

• Stoplight,
• Openapi-gui (OS).

Talk summary

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

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