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

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.