Ford Motor Company has implemented a DocOps approach to enhance their API documentation and developer experience, recognizing the importance of APIs in their mobility services. The company's efforts include establishing developer personas, creating a unified API catalog, and automating API publishing processes, all aimed at improving documentation quality and accessibility. Key lessons learned emphasize the need for transformation, collaboration with product teams, and the value of iterative improvements over perfection.

1. From Zero To Sixty
Driving A DocOps Based Approach To APIs At Ford Motor Company
CHICAGO
8 April, 2019

2. 2
Is Ford Really An API Company?
 Established in 2016 as a
subsidiary of Ford
 Mission: Design, build, grow
and invest in new mobility
services

3. 3
Mobility Services Require An Ecosystem Built Around APIs

4. 4
Yes: Ford Is An API Driven Company
City
Solutions
Infotainment
Telematics
Location
Services
FinTech
Autonomy
Predictive
Systems
Ride Sharing
Fleet Services
Charging
Networks
Smart
Ownership
Parking
Data
Analytics
Vehicle
History

5. How Does Working In A Global
Company Impact Our APIs And
DocOps?

6. 6
Ford Has A Global Footprint And 116 Years Of Technical Debt
166,000 people working
in plants and offices
around the world

7. 7
Alignment Requires Much Effort
Global Enterprises Are One Big Person, Made Up Of Many People

8. 8
Various Guardrails Are In Place To Protect
Purchasing
Contracts
Information
Security
Policy
Open Source
Architecture
Financial Policy
Regulations

9. 9
Yet Mobility Has The Need To Sometimes Go Off Road

10. 10
Finding Content Is Often Difficult
I know that there it
is somewhere
around here…..

11. 11
Legacy Information Is Not Always Easily Consumable

12. Why Are We Doing DocOps?

13. 13
Developers Believe It is Important
Source: Programmable Web
0 1 2 3 4 5
Presentation
Navigation
Consitency Across Products
Clarity
Non-Tech speak
Discoverability
Consistency Within Product
Preqs/Dependencies Present
Source: Ford Hackathon Survey of developers
InternalExternal
Ford developers value the visibility of a
product’s prerequisites and dependencies
above everything else
Developers value complete and accurate
documentation more than uptime in their API
decision making

14. 14
A Good Developer Experience Is Based on Content
Source: Acrolinx
The hidden C
behind CX
ontentIt is almost too obvious to say
out loud, but customer
experience has become the
most important determinant
of success or failure

15. 15
However, Agile Practices Can Be in Opposition To Good Docs
Many developers focus on the 4 items on the left and
take them as license to completely ignore their
counterpoints on the right

16. Ford Mobility Approach to
DocOps

17. 17
Approach: Conducted An API Scavenger Hunt
Complete An “As Is” Assessment For Your API Products

18. 18
Approach: Exposed Our Hidden Factories
Charlie Chaplin Modern Times
Document The “Work-Arounds”
Developers Put In Place To Get
Their Jobs Done

19. 19
Approach: Changed Our View On What Is Content
Static
Dynamic
Real-time
DocOps Practices Must Encompass ALL Content Types

20. 20
Approach: Exposed APIs With Meaningful Metrics
Visualize API Consumption, Re-use, Error Rates, And Other Key KPIs

21. 21
Approach: Enabled Self Service API Onboarding
Establish A Culture of Self-Service

22. 22
Approach: Provided Meaningful Developer Assistance
Eliminate Developer Pain Points Via Automation and Education

23. What Have We Accomplished So
Far?

24. 24
Established Internal Developer Personas

25. 25
Picked A REST API Standard
what do our
APIs and I
have in
common?
we both
have
SWAGGER
Evangelized
The Standard

26. 26
Launched An MVP Developer Portal
Catalog
Get Started
Home Landing Page
Develop
Ask The Community
What’s Inside?

27. 27
Content: Created A Unified API Catalog
Mobility needs to build docs
on top of large and sometimes
fragmented ecosystem
Multiple API gateways
Multiple API managers
APIs not managed via
an API Manager
APIs buried in legacy
apps
Swagger
Postman Collection
Sequence Diagram
API 1 Pager
Geospatial API

28. 28
Content: Developed API 1 Pagers To Help API Discovery
Static

29. 29
Static
Internal
contacts are
very important
Non 24x7 systems,
languages, volume
Regional
availability
Adoption
Upstream and
downstream
Preconditions and
hidden gotchas
Key Artifacts
Content: API 1 Pagers
Internal developers have
greater content needs vis-a-vi
external developers

30. 30
Automate: Hooked API Publishing Into CI/CD Pipeline

31. 31
Automate: Implemented API Linter Into CI/CD Pipeline
Open API 2.0
+
API Style
Guide

32. 32
Content: Implemented Visual Factory Principles (Radiators)
Static
Enable public
visualization of
vital product
activities,
services and
performance
Content = Static + Dynamic + Real-time

33. 33
Talent: Hired A Content Strategist and Technical Writers
Help/FAQs UI Text User Guides
Quick Start
Guides
Glossaries e-Learning and
Classroom
DevOps
Guides
Videos API
Documentation
Software
Engineer
Product
Designer
Product
Manager
Challenge of hiring writers into an
organization that’s never really
done professional tech writing for
software products
Tech
Writer

34. 34
Outreach: Use Hackathons To Gather Developer Feedback
Static
Evangelize

35. What Have We Learned?

36. 36
DocOps practices are transformational changes and change
management is key
What Have We Learned?

37. 37
Change Only Occurs When Work Together With Your Product Teams
What Have We Learned?

38. 38
Don’t Just Focus on Static Content (Swagger is Not Enough)
What Have We Learned? - A Living Ecosystem
STATIC DYNAMIC REAL-TIME

39. 39
Humor is a Great Teacher To Help Change Behaviors
I DON’T ALWAYS RETURN
AN API ERROR
BUT WHEN I DO I USE A
200 STATUS CODE
UP TO DATE API DOCUMENTATION
NOW THAT IS SOMETHING I HAVE
NOT SEEN IN A LONG TIME
What Have We Learned?

40. 40
Above All: Don’t Seek Perfection
 Don’t spend too much
time searching for the
perfect tools… because
there are none, and they
change all of the time
 Get a few early wins,
provide something that
people can see, touch,
and interact with
 Utilize lean startup
principles, an iterative
process, and willingness
to experiment
The Ford Edsel has become synonymous with the real-life
commercial failure of the predicted "perfect" product
What Have We Learned?

41. Darren Shelcusky
Ford Motor Company
dshelcus@ford.com