Peter S. Look - Docs-as-Code: Evolving the API Documentation Experience

Peter S. Look

Senior Manager of the API Platforms & Partner Programs organization at Motorola Solutions

Peter’s presentation (video recording)

Peter's slides

Q&A

• How many people’s daily or weekly practices or habits were influenced by this change? How many people did you have to involve in turning this ship?
• Is there a contextual tipping point that you think allowed this change?
• Would you recommend this approach for teams with technical and non-technical skills that need to collaborate on documents?
• From what you said, you interact with SMEs from various dev teams to get the info needed to document the API. Are the teams always available to speak with you, or is it sometimes a challenge to get their attention? If it’s a challenge, how do you get them to collaborate?
• In retrospect, would you do something differently in this switch?
• Is there any aspect of the story that you told which you would really recommend because you think you did it really well?

An atypical ecosystem

• Atypical ecosystem: apps are deployed to a broadband-narrowband integrated network.
• There are specific operating requirements with narrowband as resources are shared: voice (which uses the narrowband) has priority over data.
• Knowledge of the narrowband network is required to implement an API.

Early choices made by the team

• The API documentation is created by the existing community of software developers inside the company (software engineers with technical writing skills).
• Using classic project management methods and development practices of tech writing teams.
• Deliver comprehensive API documentation through detailed specifications and by transferring knowledge about the system to the developer.

The problems

• Unreliable historical data leads to inaccurate project planning.
• Large project schedules are difficult to maintain, it takes a lot of time to keep them up to date.
• Breaking down the work requires complex task management skills.
• Serialized workflow and rigid resource management.
• Inflexible collaboration with agile software development teams.

Building a platform for developer relations

• External influences that triggered change: increased responsibilities and scope, refocused project management practices, using more flexible tools and resources.
• Using a DevOps platform solution not only as a developer portal but also as a work environment.
• Using a kanban board to adopt and adapt to agile development methods.
• Creating stories and determining impact for documentation as well as tools and training.
• Pros of the Kanban board: flexible and independent task management, clarity of the process (status and backlog).

Difficulties with documentation creation & consumption

• Using Microsoft Word for drafting and reviewing the documentation: its flexibility can lead to inconsistency in formatting.
• Serialized development: concurrent work on a single documentation was not possible.
• Using different tools to create resources (e.g., diagrams and charts).
• Large documentation files prone to long loading times, risk of file corruption.
• Revision history: older modifications were difficult to track.

Transition to Markdown for better experience

• Trigger conditions: earlier PoC work on automating doc pipelines, the PCs of new employees do not come with Office Suite.
• Markdown is less flexible in formatting, but that can decrease the chance of making errors.
• In Markdown, templates can be defined with an exact style guide.
• Converting large Microsoft Word files into Markdown: breaking a large documentation into smaller, logical components which are easier to work with.
• Using git (+ a DevOps platform) for version control and documentation distribution.
• Tracking changes using issues, reviewing and approving changes through merge requests, recording release versions using git tags.
• Using commit history and diff view to trace changes over time.
• Using Mermaid to codify diagrams and message flows, and eliminate binary resource files.

Trade-offs and positive gains

• New delivery method requires flexibility from the community (online distribution of documentation, mixed workflow and media for a year, reduced capacity due to tech debt).
• Consistent format output and reduced format depth for readability.
• No conversion errors (pagination, layout, hyperlinks).
• Little to no risk of file corruption (robust artifacts).
• Lower resource requirements (disk space).

Still more to do

• Complete transition to Markdown (backlog of 30+ documents that need to be converted with PanDoc).
• Refactor diagrams using Mermaid.
• Test documentation using linters (Proselint, Vale or Markdownlint).

Evolving the API documentation experience

• Evolving the API doc experience not only for the developers who read the documentation, but also for those who produce it (make the documentation more streamlined, more effective, quicker to deliver) .
• Adopting and adapting agile software development practices for project management (Kanban board for issue tracking and management).
• Docs-as-code approach: shift to “code-like” formats (Markdown, Mermaid), using dev environments and tools for version control, release management and automation.