Building a getting started guide for Aria Automation Config

Lead writer · 2022 · 1 year · 8 people · 2 min read

Created comprehensive getting-started documentation that enabled customer self-service onboarding.

Overview

Four months into my role as a junior writer, I took ownership of the documentation effort for a major rebuild of VMware's Automation Config SaaS offering. I created a new getting started guide for the platform while still learning the product myself.

Problem

Automation Config SaaS was being rebuilt with a new onboarding experience, but documentation was just a copy of the on-premises guide. The getting started guide needed a complete redesign for the cloud product. I had to redesign it while learning the product myself and staying up to date on product changes.

Approach

I took ownership of the documentation effort. After the onboarding process was finalized, I walked through the workflow myself to identify pain points, and then organized the guide around the customer journey. I kept the scope of the documentation narrow and focused only on documenting what was needed to onboard, not every feature of Automation Config itself. This also ensured that I would have minimal rework as the product evolved.

Challenges

  • Onboarding workflow changed constantly
  • Limited environment access
  • 5-month timeline to beta launch
  • Small documentation team

Key Tasks

Use longform documentation rather than topic-based authoring

Reasoning:

Breaking content across multiple pages would have forced users to load new pages and lose context between steps.

Avoid detailed explanations of product features

Reasoning:

Getting started guides are meant to help get users up and running quickly. I briefly described product features and provided links to the user guide for more information.

Alternatives considered:
  • No feature mentions at all (would leave users confused as they navigated onboarding)

Tech Stack

  • Oxygen XML Author
  • DITA
  • SDL Tridion (Content Management)
  • Ubuntu
  • PuTTY (SSH)

Impact

  • Transformed lightweight documentation to standalone, comprehensive getting started guide
    Documentation coverage
  • Beta customers could onboard independently
    Self-service adoption
  • Defined documentation delivery workflow for beta and initial availability (IA) documentation
    Beta distribution process

The guide became the primary resource for customers and SREs spinning up instances. By organizing the content around the customer journey, users followed a clear path from signup to connecting their VMs to Automation Config. Feedback from beta customers directly shaped content delivery for the initial availability (IA) release. The guide also scaled well through the IA and general availability (GA) releases.

Learnings

  • Going through the onboarding workflow myself increased my own understanding of users' pain points and needs
  • Adding code samples that users can copy helps to reduce friction in onboarding
  • Keeping scope tight when documenting beta features prevents documentation churn
All projects