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.
How to Troubleshoot Apps for the Modern Connected Worker
Evolving API Docs Experience with Markdown
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
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
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