Peter S Look
Motorola Solutions
Docs-as-Code: Evolving the API Documentation Experience
About the talk:
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.
About the author:
Peter Look is a software engineering professional with over 15 years experience in Developer Relations. In his most recent role, he is Senior Manager of the API Platforms & Partner Programs organization at Motorola Solutions with responsibility over Engineering and Business Operations. Peter is formally educated as an electrical engineer but started his career as an embedded systems engineer developing software for two-way radio products used in land mobile communication systems. He is a graduate of the University of Illinois and of Northwestern University. Chicago is Peter’s hometown.
