ROSA Day 1 Experience (Console + User Guide)

This project demonstrates the development of an automated prerequisite validation experience for the console, as well as getting started documentation for Red Hat OpenShift Service on AWS (ROSA), a managed service for deploying containerized applications with Red Hat OpenShift on AWS. I created UI text and help panels for the new console experience, and getting started documentation for the ROSA User Guide as components of a cohesive Day 1 experience, shipping with console’s launch in Q4 2022.

The work addressed two customer friction points: manual prerequisite verification requiring navigation across multiple AWS consoles and lack of AWS-native getting started documentation. I participated in weekly design workshops with the ROSA PM, UX Designer, Console Developer, and Front-End Engineer through Q4 2022, while creating getting started documentation in parallel through Q3 2022. I also collaborated with Red Hat writers to ensure terminology consistency across both AWS and Red Hat documentation platforms.

ROSA Get Started page with automated prerequisite validation checking account readiness before cluster deployment

The Challenge

Reducing Friction in ROSA Enablement

Enabling ROSA required customers to verify their AWS accounts met specific prerequisites for Service Quotas, IAM roles, and ELB service-linked roles before creating clusters. This verification process was entirely manual. Customers had to discover prerequisite requirements through documentation, then check their AWS accounts across multiple consoles. The process provided no proactive visibility into account readiness, leading to deployment failures discovered late when customers had already invested significant time.

Compounding this automation gap, AWS lacked native getting started documentation for ROSA. All Day 0 and Day 1 documentation lived exclusively on Red Hat’s documentation site. ROSA customers, accustomed to finding prerequisite and deployment information in AWS service user guides on docs.aws.amazon.com, encountered navigation friction when forced to look elsewhere. This positioning confusion made ROSA appear less integrated as an AWS-native service than customers expected.

Technical complexity spanning multiple AWS services:

Service Quotas: EC2 instance limits, EBS volume quotas (gp2/gp3), Elastic IP limits
IAM: Account roles, trust policies, permissions
ELB: Service-linked roles for load balancer management
AWS Marketplace: Contract enablement requirements

Service Quotas help panel explaining why EC2 and EBS quota limits matter for ROSA cluster creation

Designing the Prerequisite Validation Experience

Console Automation and Help Panel System

The prerequisite validation page needed to check three AWS account requirements automatically: ROSA enablement status, Service Quotas sufficiency, and ELB service-linked role presence. I created UI text and help panels that explained each validation check while showing account readiness status in real-time.

Console improvements:

Page introductory text framing the purpose and setting expectations for what customers would accomplish
Real-time validation status for each prerequisite with success and error states
Actionable error messaging identifying specific quotas requiring adjustment when validation failed
Info callouts explaining why each prerequisite mattered and addressing common misconceptions about billing and enablement
Validation checkpoint confirming prerequisites before allowing customers to proceed to cluster creation

Help panel system (6 panels):

I created contextualized help panels addressing knowledge gaps for customers coming from on-premises OpenShift who might be unfamiliar with AWS service integrations:

ROSA Enablement: Explained Marketplace subscription model and addressed billing concerns
Verify Prerequisites: Described automated validation process and what the prerequisite validation page checks
Service Quotas: Defined Service Quotas service for customers unfamiliar with AWS quota management, explained minimum requirements across EC2, VPC, EBS, and ELB
ELB Service-Linked Role: Clarified why load balancer role requirement existed and how it enables load balancer management
AWS Account Requirements: Explained IAM roles and trust policy setup
AWS and Red Hat Account Connection: Described Marketplace integration and cross-company account linking

Each help panel linked to detailed documentation for customers needing deeper configuration guidance, creating a natural path from console validation to comprehensive AWS documentation.

Help Panel Screenshot Help panel providing contextual guidance on ROSA enablement prerequisites and automated validation process

Designing the Documentation Experience

Creating AWS-Native Getting Started Resources

While developing console UI text, I created comprehensive getting started documentation for the AWS ROSA User Guide through Q3 2022. This addressed the documentation gap customers experienced when looking for prerequisite and deployment information on docs.aws.amazon.com.

Docs-as-product approach:

Documentation was designed as part of the complete enablement surface, reinforcing terminology and prerequisites introduced in the console UI. Console help panels linked to detailed documentation; documentation reflected console validation checks. This connection ensured customers experienced consistent guidance whether they started in the console or documentation.

Cross-company collaboration:

I worked with Red Hat documentation writers to ensure a unified Day 1 narrative spanning both AWS and Red Hat documentation sets. This collaboration ensured both platforms used consistent AWS service terminology, reducing cognitive load for customers navigating multiple documentation sources during deployment. We aligned on how to describe Service Quotas, IAM requirements, and ELB roles so customers wouldn’t encounter conflicting information.

Published AWS Documentation

Getting Started with ROSA Landing page orienting customers to different ROSA deployment workflows (CLI-based, PrivateLink)

Set Up Prerequisites Detailed prerequisite requirements and configuration instructions customers validated in console

Create a ROSA Cluster Using the CLI Step-by-step CLI-based cluster creation workflow with STS authentication

Create a ROSA Cluster Using AWS PrivateLink PrivateLink deployment workflow for customers requiring private cluster connectivity

Information architecture decisions:

I created a getting started landing page directing customers to the appropriate workflow for their use case (CLI-based vs PrivateLink-based deployment). A separate set-up page surfaced all prerequisites in one location, making it easy for customers to verify readiness before beginning deployment. Workflow-specific deployment procedures provided step-by-step guidance tailored to each approach.

Prerequisites documented in the set-up page aligned exactly with in-console validation checks, creating a consistent story. Customers could validate prerequisites in the console, then reference detailed configuration steps in the documentation without encountering conflicting information about what was required.

Console and documentation connection:

Console help panels linked directly to relevant sections in the set-up documentation, providing a clear path from automated validation to detailed configuration guidance. Both surfaces used consistent AWS service terminology, so customers didn’t need to mentally translate between different naming conventions. Customers could self-service through the console, then reference documentation for detailed procedures when needed.

Impact and Outcomes

Cohesive AWS-Native Enablement Experience

The coordinated console and documentation experience shipped in Q4 2022, creating ROSA’s first complete AWS-native enablement path. The documentation filled a customer-identified gap, providing prerequisite and deployment guidance customers expected to find in the AWS ROSA User Guide. Customers could now discover all necessary prerequisite information on docs.aws.amazon.com, eliminating the friction of hunting across partner documentation sites for foundational enablement information.

This foundation became the base for subsequent ROSA features, including the 2023 HCP billing integration that built upon the same prerequisite validation and documentation framework. The patterns established for automated prerequisite checking and coordinated console-documentation development became the template for future ROSA console work.

Automated Enablement

Prerequisite page eliminated manual verification across multiple AWS consoles

Improved First-Deployment Success

Console validation and documentation guidance increased time-to-first-cluster success rates

AWS-Native Documentation

Getting started resources on docs.aws.amazon.com provided prerequisite and deployment workflows in the location customers expected

Unified Experience

Console help panels and documentation reinforced same prerequisites with consistent terminology

Key Takeaways

Console and Docs Are One Experience

Customers don’t distinguish between console and documentation when trying to enable a service. They’re navigating a unified product experience. Designing console UI and documentation together created better outcomes than treating them as separate deliverables that happen to reference each other. When prerequisites aligned across both surfaces, customers experienced less cognitive load and fewer contradictions.

Meet Customers Where They Expect to Find Information

ROSA customers expected to find prerequisite and deployment documentation in the AWS ROSA User Guide, not exclusively on a partner site. Their experience with other AWS services set this expectation. Meeting customers where they naturally looked for information positioned ROSA more clearly as an AWS-native service and reduced navigation friction that could have discouraged adoption.

Embed Early to Influence Design

Weekly workshop participation enabled me to identify information gaps and suggest UI improvements before designs were finalized. I could propose simplifications and terminology changes when they were still easy to implement rather than after console code was written. Being in the room when design decisions happened was more valuable than reviewing completed mockups where changes would be costlier.

Consistent Terminology Reduces Cognitive Load

Coordinating with Red Hat writers ensured consistent AWS service terminology across both documentation platforms. When customers navigated between AWS and Red Hat resources during deployment, they encountered the same language describing Service Quotas, IAM roles, and ELB requirements. This reduced confusion and made both documentation sets more trustworthy as sources of accurate information.

View Live Work

ROSA Console View the live prerequisite automation experience (requires AWS account)

ROSA Getting Started Documentation Published prerequisite and deployment documentation on docs.aws.amazon.com