“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.
“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?
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 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.
It is a very different programming paradigm which requires complex documentation, uses vendor lock and where developers touch more infrastructure.
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.
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.
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:
individuals and interactions vs. rocesses and tools,
working product vs. comprehensive documentation,
customer collaboration vs. ontract negotiation,
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.
DocOps practices are transformational changes - change management is key.
Change only occurs when product teams work together.