Writing a how-to guide for Aria Automation Config's cloud API

Technical Writer · 2023 · 5 months · 2 people · 3 min read

Developed comprehensive API documentation that enabled cloud customers to programmatically manage their Automation Config Cloud instances

Overview

Created API documentation for VMware's Automation Config Cloud API from scratch, including code samples, example requests and responses, and troubleshooting content.

Problem

The engineering team released a new API for Automation Config SaaS. Because it was an RPC API, I had no OpenAPI specification to work from. Information also lived in multiple places, dependencies changed, and server URLs were updated regularly. I had to consolidate scattered information and figure out how to document an API with no reference for the API's behavior.

Approach

I took a very hands-on approach, deploying my own Linux VMs to test the API workflows myself. This helped me verify which versions of dependencies actually worked, which regional URLs were correct, and what the actual user experience was. Because this was a how-to guide, I structured the documentation around a clear outcome: making a successful API call.

Challenges

  • No OpenAPI specification to reference
  • RPC API with non-standard patterns (no REST endpoints, no GET/POST conventions)
  • Engineering team was small with limited availability for code samples
  • API code changed frequently during the documentation period
  • Had to generate code samples myself
  • Had to independently verify authentication flows and regional endpoints

Key Tasks

Test every code sample and workflow myself

Reasoning:

Testing the workflow myself helped me identify and document what actually worked versus what was documented but broken. It also helped me ensure that I understood the user experience firsthand and could document any friction points.

Create code samples in both Python and cURL

Reasoning:

The engineering team requested both languages to support different user tooling preferences. I implemented both and tested each to ensure accuracy.

Structure the guide around the user's first successful API call

Reasoning:

The ultimate goal was getting users to programmatically retrieve a list of all jobs. Building the guide around that goal meant the documentation had a clear outcome.

Tech Stack

  • Oxygen XML Author
  • DITA
  • SDL Tridion
  • Python
  • cURL
  • Linux (Ubuntu)
  • VMware Cloud Templates

Impact

  • Owned full API documentation lifecycle instead of asking engineers for code samples and examples
    Reduced engineering overhead
  • Personally tested every code example to verify correctness
    Code sample coverage
  • Users could make their first successful API call within minutes of reading the guide
    Customer time-to-value

By taking on the testing and validation work myself, I freed up the engineering team to focus on product development. My hands-on approach caught some inconsistencies, such as missing dependencies and unclear requirements around user roles for API key generation.

Learnings

  • Testing workflows yourself can help identify critical usability gaps
  • Providing code samples in multiple languages can lower barriers to adoption
  • Hands-on testing deepens your product knowledge and builds credibility with users and engineers

Notes

The hands-on testing for this project was important. Failing to complete a task provided valuable data that I used to improve my drafts. Where did I fail? Was this user error? Or is there something missing from the documentation that I need to know to complete my task successfully?

This project also solidified a core belief for me: technical writers need to do what their users do. You can’t identify critical pain points from SME interviews or reading Confluence docs. You must complete the task yourself to fully understand your users.

All projects