We are a software engineering team creating API docs. Docs are authored using Instructional Design principles to narrate use-cases and practical API implementations. This talk shares why & how we've applied software development practices to evolve our document tooling, creation, & delivery methods. Our APIs describe asynchronous protocols used for embedded software (firmware) components in a digital 2-way radio communications system. The API is protocol data unit (PDU) based and its definition is described in a proprietary format; consequently, well-known API formats, such as Swagger/OpenAPI, or tools, such as doxygen, are not used. Our product training and technical writing teams are very experienced in Instructional Design methods, but these teams have only written documentation for an end-user audience. Understanding software development processes is equally important as understanding two-way radio networks in order to successfully integrate with the APIs. This is the rationale for having a software engineering team develop the skillsets to write API documentation for a developer audience. With a solid foundation of API documentation in place, regular examination of engineering efficiency and developer experience is appropriate. Repeated actions can be replaced by automation. Content can be modular and re-usable. Formats can be streamlined for easier consumption. Docs can be made portable and lightweight for faster delivery.

1. PETER S LOOK
SEPTEMBER 21, 2022
Docs-as-Code:
Evolving the API
Documentation Experience
Motorola Solutions Public
https://www.linkedin.com/in/peterlook/

2. 2
THE API PLATFORMS & PARTNER PROGRAMS (A3P) ORGANIZATION
IS A DEVELOPER
RELATIONS
(DEVREL) TEAM
INCLUDES
ENGINEERING &
BUSINESS STAFF
SUPPORTS DEV
COMMUNITIES &
PRIVATE
PARTNERSHIPS
CURATES
SELECTIVE
RELATIONSHIPS
W/ DEVELOPERS
APPLICATION DEVELOPER PROGRAM (ADP)
OPERATING
WORLDWIDE
SINCE 2007
APPS ATTACHED
TO DEVICES &
SYSTEMS
EXECUTES A
“DEVELOPER-PLU
S” BUSINESS
MODEL
Motorola Solutions Public

3. 3
AN ATYPICAL ECOSYSTEM
Apps are deployed to a broadband-narrowband integrated network.
This network has specific operating requirements:
● Voice & data are transported through the system
● Resources are shared - Voice has priority over data
● Narrowband throughput is (at most) 1.2Kbps (vs >10’s Mbps for broadband)
Requires network knowledge to implement the API; network behavior is difficult to abstract
Motorola Solutions Public

4. 4
EARLY CHOICES
● Build a software team w/ tech writing skills
○ Leverage experience of engineers who built the technology
○ Support other developer success activities (i.e. training & technical services)
○ Reduce layers of knowledge transfer
○ Author doc revisions with proper context
● Apply “classic” project management methods to guide work
○ Adopt development practices of tech writing teams in company
○ Track & schedule activities - entry / exit criteria, dependencies, critical paths
● Deliver comprehensive API documentation
○ Produce detailed specs & thorough narratives
○ Organize revisions into a major release for digital publication
Motorola Solutions Public

5. 5
COMPOUNDING PROBLEMS
● Inaccurate project planning - historical data
not reliable for estimations
● Large project schedules - difficult to maintain,
required high-touch oversight
● Detailed work breakdown - task management
complexity
● Serialized workflow, rigid resource management
● Inflexible collaboration w/ software teams
executing delivery in agile manner
Motorola Solutions Public

6. 6
INSTITUTING CHANGE (ca. 2016)
● External influences
○ Org responsibilities & scope increased
○ Project mgmt practices & resources refocused
○ Flexible tooling for defining / managing work
● Building a Platform for Developer Relations
○ Selected a DevOps platform solution to use as a developer portal & work environment (kanban board!)
○ Increased alignment w/ engineering sprint plans; adopt & adapt agile dev methods
○ Assess Epics, create stories, determine impacts for docs as well as tools, training
○ Task management flexibility based on component or subject matter
○ Team empowered to manage work with independent agility
○ Clarity in progress, status, and backlog
Motorola Solutions Public

7. 7
EARLY DECISIONS & MITIGATIONS
Motorola Solutions Public

8. 8
CREATION & CONSUMPTION DIFFICULTIES
● Docs contain specs and narratives on how to use the API
○ Word / Microsoft Office - tool of choice in company; the most used file format (at the time) between teams
○ Typical flow - draft Word doc, formal tech review, make repairs, final inspection, convert to PDF & release
● Emerging problems
○ Inconsistent expertise in Word / too many ways to create a format’s look and feel
○ Difficult to ensure consistent formatting and templates
○ Serialized development / concurrent work on single doc not possible
○ Multiple tools needed to create resources such as diagrams, charts, message flows
○ Frequently modified docs become very large, prone to long loading times, risk of file corruption
○ Revision history of limited use as new changes made older modifications difficult to track
Motorola Solutions Public

9. 9
A BETTER EXPERIENCE
● Trigger conditions
○ Earlier PoC work on automating doc pipelines to build PDFs and release packages
○ New employees receive PCs with Google Workspace only; no support for MS Office / Word
● Transition to Markdown (started in March 2022)
○ Limited number of formats - templates can be defined with an exact style guide
○ Docs partitioned into smaller, manageable chunks; reusable components & concurrent development
○ Use git (+ DevOps platform) for source control and doc distribution
○ Track changes using issues; audit & approve using merge requests; record release versions w/ git tags
○ Use commit history to trace changes over time; developers use diff to learn more
○ Include Mermaid to codify diagrams and message flows; eliminate binary resource files
○ Instituted for any new docs going forward
Motorola Solutions Public

10. 10
EARLY DECISIONS &
Motorola Solutions Public

11. 11
ACCEPTABLE TRADE-OFFS / POSITIVE GAINS
● Community flexibility to new delivery method
○ Docs are completely online - docs not formatted for PDF or printout
○ Downloading docs means cloning the repo and using a Markdown viewer
○ Mixed media for at least a year - PDF docs & Markdown delivered together
○ Mixed workflow for at least a year - doc source in Word & Markdown formats
○ Reduced capacity / tech debt for 1+ year
● Streamlined workflow for internal development
○ Reduced format depth / consistent format output
○ No conversion errors - pagination, layout, hyperlinks
○ Robust artifacts - little to no risk of corruption, open/save/close & push/pull/clone performance
○ Lower resource requirements - disk space
Motorola Solutions Public

12. 12
STILL MORE TO DO
● Complete transition to Markdown
○ Backlog of 30+ docs, 4000+ pages for conversion using PanDoc
○ Refactor diagrams using Mermaid (https://mermaid-js.github.io/mermaid/#/)
○ Expect completion around August 2023
● Re-examine build pipelines
○ Test docs using http://proselint.com/ or https://vale.sh/ or https://github.com/markdownlint/markdownlint
Motorola Solutions Public

13. 13
EVOLVING THE API DOC EXPERIENCE
● Adopting & adapting software development practices to how projects are managed
○ Agile methods for project execution
○ Tools for issue tracking & management (e.g. Kanban board)
● Write docs like how you write code
○ Transform into “code-like” formats (e.g. asciidoc, markdown, mermaid) for easier development
○ Use dev environments & tools to source control, release manage, and automate
Motorola Solutions Public

14. 14
14
THANK YOU!
Motorola Solutions Public
Peter S Look
Senior Engineering Manager
Engineering & Business Operations
API Platforms & Partner Programs
https://www.linkedin.com/in/peterlook