A scalable workflow for large teams collaborating on API Portals

The key topics covered in this video:

• [00:00] What is Docs as Code?
• [01:30] What’s in an API Portal?
• [02:02] Content
• [02:36] The Content Management Team
• [03:13] Infrastructure
• [03:25] The Infrastructure Team
• [04:27] How do all these people collaborate effectively?
• [05:55] Docs as Code: A Documentation approach for better cross-team collaboration
• [07:42] How Docs as Code solves the team collaboration problem
• [08:30] Version Control
• [09:00] Use the right tool for the job
• [09:42] Automated Deployments
• [10:16] Docs as Code Demonstration using APIMatic's API Portal

Introduction

In this episode of API Conversations, host Sid Maestre explores a topic crucial for developers, product owners, and engineering leaders: improving API documentation workflows. 

Reflecting on the experiences at Lob, where the team transitioned from manually maintained API references to automated documentation via an open API definition, Sid realized the significance of a streamlined documentation process. Unfortunately, the team’s tooling at the time left much to be desired.

But what would a streamlined API documentation workflow for a large team look like?

In the world of API Documentation, finding the right balance between efficient workflows and comprehensive Documentation can be challenging. Many teams struggle with fragmented processes, poor collaboration, and the need to juggle multiple tools. 

Enter "Docs as Code" - an approach that promises to significantly improve how we create, maintain, and deploy API documentation

Understanding the API Portal Ecosystem

Before diving into the Docs as Code approach, let's break down the components of a typical API portal:

1. Content:

Going by industry conventions, the bare minimum content for a robust API portal is:

• Quick Start Guide: Essential for helping developers get started with the API.
• API Reference: Detailed information about the API endpoints.
• Technical Documentation: Includes change logs, FAQs, walkthroughs, and tutorials.
• SDKs and SDK Documentation: SDKs in multiple programming languages along with sample code.

2. Infrastructure:

Since an API Portal is a website like any other, it has the same infrastructure requirements as any website, this means:

• Website design and development
• Domain and Hosting
• CI/CD pipelines

Essential team required to build and maintain an API Portal

Building and maintaining both the content and infrastructure listed above requires the collaboration of a multidisciplinary team which may involve some or all of the following:

• Technical Writers: Draft quick start guides and detailed documentation.
• Support Engineers: Provide insights into common issues developers face while onboarding
• DevRel Engineers: Contribute to developer experience and community engagement.
• Product Managers/Owners: Ensure the documentation aligns with the overall product experience.
• Developers: Maintain and update the open API definitions. Create SDKs and SDK Documentation
• UI/UX Designers: Ensure the portal follows brand guidelines and offers a seamless user experience.
• Engineers: Build the Portal and Integrate it with existing systems.
• DevOps/IT Team: Manage deployments, CI/CD pipelines, and hosting.

Addressing Collaboration Challenges

Bringing together individuals from half a dozen product functions to collaborate over an API Portal can be challenging, especially if you’re not using the right tools and workflows for the job. 
With so many contributors, it can be hard to keep track of who did what and to prevent team members from overwriting each other's changes; challenges that aren’t appropriately addressed by many off-the-shelf API Documentation solutions. 
Due to the diversity of the team, the tooling required to contribute to an API Portal can create a barrier for entry for some team members. Training Developers, Designers and Product Owners to use a common set of tools just to be able to contribute to Documentation is an unnecessary task. The ideal solution should enable each team member to keep using the same tools that they are already familiar with.

What is Docs-as-Code?

Docs-as-Code is an approach where Documentation is built and maintained using the same tools and processes that Product teams use to build software. 
Here's what it entails:

• Plain text files: Documentation is written in formats like Markdown, JSON, or YAML.
• Static site generators: Tools that convert plain text files into a fully functional API portal.
• Version control: Typically Git, for tracking changes and facilitating collaboration.
• CI/CD integration: Automated testing, building, and deployment of documentation.

Benefits of Docs as Code

• Enhanced collaboration: Leveraging Git's features, teams can track changes, attribute edits, and easily roll back when needed.
• Familiar tooling: Team members can use their preferred tools (e.g., VS Code, Sublime Text, or Markdown editors).
• Automated deployments: CI/CD pipelines allow for seamless updates to the live documentation.
• Version control: Easy tracking of changes, branching for different versions, and merging updates.
  

Conclusion

The Docs as Code approach offers a powerful solution to the challenges of API documentation. By leveraging familiar developer tools and workflows, teams can collaborate more effectively, maintain high-quality documentation, and streamline the deployment process. For technical teams looking to improve their documentation workflow, Docs as Code is certainly worth considering.
Remember, the key to success lies in choosing the right tools for your team and establishing clear processes for contribution and review. With Docs as Code, you can transform your API documentation from a fragmented afterthought into a seamless part of your development lifecycle.

Learn more about APIMatic's Docs as Code capabilities in our Documentation or reach out for a Product Demo.