The art of starting: how we reimagined the Palette Getting Started journey

First impressions count

Most software product doc sites have a “Getting Started” section for new users. In fact, we’d argue that few pages are more important: a well-crafted product introduction gets users off to a flying start, so they feel confident exploring features on their own. A poor one can frustrate prospective users into giving up entirely. 

It’s a real challenge to make a Getting Started experience for a product as powerful and versatile as Palette. We cater to so many different environments and use cases, and have such a broad feature set — how do you boil it all down into one self-guided, step-by-step experience? 

Just as importantly, our documentation site caters to users from diverse industries, job roles and technical backgrounds. You might be a seasoned platform engineer evaluating Palette for your production deployments, or you might be an app developer that’s brand new to Kubernetes.

Rising to the challenge

Regular readers will know that the Spectro docs team has high standards, and we relish a challenge like this. 

We’re all engineers ourselves, and we’ve all felt the pain of digging around an outdated or poorly structured docs site, before turning in desperation to Reddit, YouTube, or Stack Overflow. We believe our users deserve better than the usual SaaS docs experience. 

So a few months ago we kicked off a project to take our Getting Started journey to the next level. In this blog we’ll take you on a behind-the-scenes tour of what we did, and what it means for you as a user. We hope you’ll find some insights to help guide you in your own documentation or internal user enablement efforts.

Step 1: Defining what good looks like

We started by describing three target outcomes. While completing a best-in-class onboarding, users should:

1. Get hands-on instruction covering their most common workflows. Platform engineers, our primary audience, love learning and solving problems. They respond best to applied learning that solves issues they are interested in or improves their day-to-day operations.
2. Achieve ‘win experiences’. A great onboarding experience needs to provide regular ‘Eureka!’ moments, where the user sees a concrete result from the applied work they are putting in. These wins help motivate and provide more efficient learning, too.
3. Feel challenged and inspired. The Getting Started journey shouldn’t be limited to essential, straightforward content. We want our learners to feel challenged while learning and inspired to continue learning even after they complete the Getting Started section. It’s about real learning, not just copying and pasting.

These principles provided a North Star for all our efforts. With a clear mission, the next step is to continue exploring the problem space and find solutions.

Step 2: Researching our user personas

If we’re to hit our first principle and cover our users’ most common workflows, we needed to really understand their behaviors and what they would expect to get from the Getting Started section.

In building out these user personas, it’s tempting to rely on your gut instinct, but instead we conducted thorough research to tap into the real-world customer insights we have across our teams. 

We interviewed fellow Spectronauts from across the business. We spoke to our customer success team, drawing on the insights they’ve gained through the QBRs they hold with customers. We tapped into our sales and marketing teams, who speak to the community every day at events and in meetings. We surveyed Engineering, QA, Product and Support for insight into where customers need help and are showing interest.  

We ended up with three personas: platform engineers, application builders (the traditional app dev), and new users from existing customers. The overwhelming conclusion was that the Getting Started section should cover the following key aspects of Palette: 

• Creating and modifying Cluster Profiles. 
• Adding Packs to Cluster Profiles.
• Deploying clusters to the most popular Cloud Providers that Palette supports. Amazon Web Services (AWS), Microsoft Azure, Google Cloud Platform (GCP), and VMware are the cloud providers most often used with our platform. 
• Performing Day-2 Operations such as scaling, upgrading, and security best practices.

The internal user research also pointed out that hands-on instruction is the format we should focus on to ensure that learners clearly understand the outcome after they complete the Getting Started training.

Step 3: Structuring the project for phased delivery

Our Getting Started revamp was a large project, and as part of our Problem Requirements Document (PRD), we scoped out delivering the work in two phases. The first phase focused on repurposing existing content, while the second involved writing and producing new content.

‍

Beyond the PRD’s definition of scope and delivery, we found the Request for Comment (RFC) format extremely helpful for discussing implementation details and exploring the structure of the Getting Started section. We wrote one RFC document for each phase of the PRD.  

One of the key decisions was around the information architecture of the Getting Started section. This decision is crucial as it affects the flow of information and the user journey. We considered two options:

• The Task-Centric approach organizes information according to the task the user is trying to accomplish. This approach builds on the hypothesis that learners already have a specific task or goal at the beginning of the Getting Started section.
• The Cloud-Centric approach organizes information according to the cloud provider where operations are being performed. This approach builds on the hypothesis that learners already have a specific cloud provider they want to use when they start the Getting Started section. They also typically have the required credentials, having previously signed up and used their chosen cloud provider.

Each approach has tradeoffs, but we ultimately chose the Cloud-Centric approach because it:

• Resulted in shorter pages, presenting users with only the content that fits their infrastructure and in-house expertise
• Aligns with how our customers and learners explore the rest of our documentation. 

You can see the page organization of this approach in the following diagram. 

Step 4: Sprinkling some storytelling magic

The Getting Started section is the entry point for Palette newcomers, and it needs to be relevant, engaging, and easy to understand. We decided to shoot for an extra level of engagement by tying all the concepts together in a single narrative. Relating information to a story and use case helps new learners retain it.

We created a fictional company, Spacetastic Ltd., for this purpose. They are a startup that teaches kids worldwide about the wonders of space and astrophysics. We also created four fictional Spacetastic employees, representing the personas we established during planning. 

• Anya is a Lead Astrophysicist. They are the team's dreamer, pushing the company to keep growing and stay focused on the mission they are trying to achieve.
• Wren is a Founding Engineer. They are responsible for implementing all the new features and focus on keeping developer velocity high. They correspond to the application builder persona. 
• Kai is a Platform Engineer responsible for keeping the platform reliable and scalable. Because they focus on production readiness and SLAs, they are naturally skeptical about relying on partners for production workloads. As their title indicates, Kai corresponds to the platform engineer persona.
• Meera is the Head of Cybersecurity. They focus on bringing security and privacy to everything they do at Spacetastic. They know that SecDevOps is an ongoing process, not an exercise you do once and forget about.

We frame every tutorial with a discussion from the Spacetastic team. They discover and learn about Palette alongside our learners, just as any new user persona, shedding light on how to use Palette to solve real-world problems. We opted to present the story as written dialog instead of creating a video or animation, because the written medium is the most accessible, and easier to maintain — but we accompany the discussions with visuals like the one below.  

Using roleplay characters also enables us to make the technical text a bit more playful and add a real-world perspective to the documentation. 

For example, Wren is a skeptic and is reluctant to rely on Palette in production. They learn more about Palette as the story progresses, voice their concerns, and slowly change their opinion by the end of the Getting Started section. 

"The Spectro Cloud team has provided our Palette accounts," says Kai. "I have followed their setup guide and have added our cloud accounts. I can already tell at first glance that they offer many Kubernetes customization features."

Wren joins Kai in looking at the Palette dashboard. "I'm interested to learn more, but I never believe in magic solutions. We should thoroughly review their Getting Started material to ensure Palette is a good fit for us."

These exchanges allow us to address the business decision-making aspects of successful Palette adoption, not just the technical aspects.

The storytelling is also reflected in our demo application used throughout the Getting Started section. We modified the Hello Universe application to reflect the Spacetastic fictional brand and provide the functionality users might expect from the platform. 

Storytelling has elevated the Getting Started section. We recommend this approach for any technical documentation site that wishes to create more compelling stories. The only caveat is that the stories should be meaningful and concise.

The results

Our revamped Getting Started pages are live, and we’re already seeing the impact. They receive 28% of all Docs monthly sessions, and users spend an average of 6 minutes on each page, which is an excellent indicator of engaging content. 

Just as importantly, we’ve received overwhelmingly positive feedback from existing, new, and prospective customers who have followed the Getting Started tutorials. 

Your next steps

If it’s been a while since you checked out the Getting Started section of our docs, why not go take a look? You can use these pages to onboard new users in your team to Palette, upskill on aspects of the platform you haven’t experienced yet, or get a quick refresher on best practices. 

If you’re responsible for docs or user education in your business — perhaps enabling your developers on how to use your IDP — you might be able to learn from our experiences when focusing on your own Getting Started content. For us, the key takeaways are:

• Know your audience. Your learners’ needs and concerns are fundamental to all the documentation you write. At the beginning of the process, take the time to gather all the internal knowledge and make all decisions based on this.  
• Deliver, then refine. Make sure you deliver changes iteratively, giving the most time to react to any early user feedback. 
• Solve problems and tell stories. Instead of just presenting technical details, focus on explaining how to solve real problems. This approach will help you craft compelling documentation and help learners retain information. 

Finally, if this blog has sparked your interest and you want to try Palette, contact us for a quick 1:1 demo.