Seamless Landing Zone For Our Docs¶
These past few months, we've invested a lot of time as a team working to create a more seamless experience for our customer-facing product documentation. While we built a lot of content covering key functionality of the platform, one of the key questions that would arise from our readers was how do I know where to start?
In order to facilitate this, we've created a new landing page for our documentation which is much like a landing where readers have a better idea of where to start. Looking at the screenshot below, we've specifically attempted to tackle the following:
- More clarity on what is contained in each section of the docs so a user doesn't have to click around to find out.
- Centralizing all the core product documentation versus it being spread in multiple tabs.
- An overview of all the themes of rich functionality and content, from core product documentation, to security docs, to CNCF recipes that is available to read and consume via the Rafay platform.
- Have a clear delineation between our tutorials/getting started guides versus what is in the core documentation.
What I want to do next is take an example of a key piece of functionality and explain how a reader can navigate our docs to build a deeper and hands-on understanding.
Let's take the following example: Say you want to learn about all the great functionality Rafay has with provisioning and managing AWS EKS Clusters. Let's look at the workflow of how you can navigate our documentation website:
graph LR A[Try the functionality using the Get Started Guide] --> B[Go to the overview section of the core documentation] --> C[See your options for automation and consumption]
Let's look at each step in more detail:
Step 1: Trying the functionality using our Get Started Guides¶
If you want to learn about EKS Lifecycle in Rafay, one of the best places to start is our Get Started Guide where there are simple step-by-step instructions that give you a gist of what the platform has to offer in terms of the specific capability you want to learn more about. This is the best place to get hands-on and build a foundational understanding without getting into the weeds.
For example for AWS EKS Lifecycle click Getting Started/Tutorials -> Amazon EKS -> Cluster Lifecycle
Step 2: Getting In-Depth With the Core Docs¶
Now that you've gone through the getting started and understood the core functionality, you want to build a deeper understanding to understand how to operate this with your organization. For example, maybe you want to learn about:
- the IAM permissions that Rafay needs to operate EKS
- which EKS versions are supported by Rafay
- how Rafay uses cloud credentials to access AWS
- what VPC Networking configurations are supported by Rafay
- whether configurations can be templatized to support a fleet of EKS cluster deployments
This is where our core product documentation comes into play as the core documentation addresses all the workflows, design considerations, and support on the platform.
For example, if I want to learn about how to configure your IAM policies for Rafay to provision EKS clusters I can go to:
Documentation -> Clusters -> Amazon EKS -> Overview -> IAM Policy
Step 3: Seeing your options for automation and consumption¶
Now that I understand all the core functionality that Rafay supports for AWS EKS, let's say I wanted to learn about how I can consume this. Rafay supports the following consumption types:
- CLI (RCTL)
- Rafay Terraform Provider
Let's say for example I wanted to automate EKS cluster provisioning with the CLI as it supports declarative YAML specs and can easily be automated. In order to learn about this you can navigate to the following:
Documentation -> Automation -> CLI -> Commands -> Clusters (or go to CLI -> Setup -> Overview if you want to set this up right away)
For next steps, there's plenty more you can do from the documentation landing page including:
- Services: Learn about all the turnkey services such as Cost Management or Network Policy Manager via Cilium that Rafay supports
- Recipes: What if I want to integrate CNCF open-source software, for example Backstage for developer-self service, or support other integrations, for example SumoLogic for logging