Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Getting started sections #2169

Merged
merged 13 commits into from
Apr 25, 2024
4 changes: 2 additions & 2 deletions src/content/getting started/_index.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
title: Getting started
description: First steps new customers need to perform in order to have their Cloud Native Developer Platform ready to be used by their teams.
description: A step by step customer journey to start building a cloud-native developer platform.
pipo02mix marked this conversation as resolved.
Show resolved Hide resolved
weight: 80
last_review_date: 2024-03-07
last_review_date: 2024-04-05
owner:
- https://github.com/orgs/giantswarm/teams/sig-docs
---
30 changes: 30 additions & 0 deletions src/content/getting started/_template.md.tpl
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
---
title: Short title case for this page, it is shown as title in upper section and menu
pipo02mix marked this conversation as resolved.
Show resolved Hide resolved
description: More than 70 chars describing the goal of the page.
pipo02mix marked this conversation as resolved.
Show resolved Hide resolved
weight: from 10 to 100. Lower is higher in the list.
pipo02mix marked this conversation as resolved.
Show resolved Hide resolved
last_review_date: 2024-03-19
owner:
- https://github.com/orgs/giantswarm/teams/${OWNER}
user_questions:
- List of questions that users might ask about this topic.
pipo02mix marked this conversation as resolved.
Show resolved Hide resolved
---

Today, getting started pages are all about guiding a new user, platform engineer, to start to build their platform with Giant Swarm. The articles are order to be follow one after the other to show all features we offer from the suffice. Dont go to deep into the topics, we have tutorials or reference pages for that purpose, here is just an introduction.

Recommended sections can help you to start with the article:

## Introduction

General definition of the area/topic you are going to develop. Since this is a step across the getting started section it has a previous and after page entry, so be aware it has continuity.

## Prerequisites

Indicate if the user needs to have installed any specific tool or should have read or prepared their local environment before.

## Steps

List of sequence steps that users will follow to accomplish the goal described in the introduction.

## Conclusion

Wrap-up of what has been done. Comment what it is next, so the user can continue the journey
11 changes: 11 additions & 0 deletions src/content/getting started/access-to-platform-api/_index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
title: Access to the platform API
description: Learn how engineers access the platform API to provision new workload clusters or deployed applications.
pipo02mix marked this conversation as resolved.
Show resolved Hide resolved
weight: 30
last_review_date: 2024-04-01
owner:
- https://github.com/orgs/giantswarm/teams/sig-docs
user_questions:
- How can I access the platform API?
- What do I need to do to access the platform API?
---
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
title: Configure and provision your first workload cluster
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it should mention "first". There's no difference for the first one and subsequent clusters, and this marks it as beginner article unnecessarily.

"Configure and provision" is also too much. Those words add no value and can only create confusion. It's not much more than one simple step, so we should describe it as such (= "create").

This was our previous title (changed to active tense, while previously we had "Creat_ing_ ... install_ing_ ..."):

Suggested change
title: Configure and provision your first workload cluster
title: Create a workload cluster and install applications

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I looked at it from a customer onboarding journey, so I thought first was a good idea but I am good with your point

linkTitle: Provision your first workload cluster
description: Experience the steps to configure and provision your first workload cluster using the platform API.
weight: 40
last_review_date: 2024-04-05
owner:
- https://github.com/orgs/giantswarm/teams/sig-docs
user_questions:
- How do I configure and provision my first workload cluster?
- What do I need to do to configure and provision my first workload cluster?
---

<!-- Easy happy path to create the first WC (probably tabs per provider), showing storage and scaling bits -->
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
title: Configure the app platform to build the platform capabilities
linkTitle: Start with the app platform
description: Deploy your first application with the app platform and learn how it works.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These 3 sentences don't match up.

The user does not configure the app platform or environment. They install a glorified Helm chart with simple tooling, or in summary, install an app (and maybe make minor .Values.xyz choices).

Let's also rename the directory accordingly once we've found a matching title here.


My first idea:

title: Install applications using the app platform
description: Overview of the app platform and installation of an app in a cluster.

Not really sure – are we giving an overview of the app platform here? I rather would not do that in this article. It should remain instructional. Explaining how to find an app (happa/catalog) and install it (with one, very typical example such as nginx-ingress) should suffice here, so we don't explode the scope. So maybe rather:

Suggested change
title: Configure the app platform to build the platform capabilities
linkTitle: Start with the app platform
description: Deploy your first application with the app platform and learn how it works.
title: Install an application using the app platform
description: Add capabilities to your platform by deploying applications from our catalog.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are we giving an overview of the app platform here?

No it is a practical intro to go across entire platform journey

weight: 50
last_review_date: 2024-04-05
owner:
- https://github.com/orgs/giantswarm/teams/sig-docs
user_questions:
- How do I configure the app platform to build my capabilities?
- What do I need to do to configure the app platform to build my capabilities?
---

<!-- Explain briefly how do we configure our environment to deploy a component in one of our clusters (For example ESO) -->

Check failure on line 14 in src/content/getting started/configure-app-platform-to-build-your-capabilities/_index.md

View workflow job for this annotation

GitHub Actions / Front matter problems

Found 1 severe problems

FAIL - There must be a newline character at the end of the page to ensure proper parsing
pipo02mix marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
title: Observe how your app is performing
description: Check your app metrics and logs with the platform built-in observability tools.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do we mean by "your app"? I guess GS managed apps and not really customer workloads (since they would have to use our observability tooling for that)?

Maybe:

Suggested change
title: Observe how your app is performing
description: Check your app metrics and logs with the platform built-in observability tools.
title: Observe your clusters and apps
description: Check cluster and app metrics and logs with the observability tools provided with the Giant Swarm platform.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do we mean by "your app"? I guess GS managed apps and not really customer workloads (since they would have to use our observability tooling for that)?

Since the entire Getting Started is a journey, the app that you install in the step before is the one we use to show the logs or security feature in next sections

weight: 70
last_review_date: 2024-04-05
owner:
- https://github.com/orgs/giantswarm/teams/sig-docs
user_questions:
- How do I observe the platform metrics and logs for my application?
- What do I need to do to observe the platform metrics and logs for my application?
---

<!--
Show how to access Grafana and basic dashboard and logs
-->
11 changes: 11 additions & 0 deletions src/content/getting started/platform-bootstrap/_index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
title: Platform bootstrap
description: Comprehend the different phases of the platform bootstrap process, how the management cluster is built and how the configuration is applied.
pipo02mix marked this conversation as resolved.
Show resolved Hide resolved
weight: 20
last_review_date: 2024-04-05
owner:
- https://github.com/orgs/giantswarm/teams/sig-docs
user_questions:
- What is the platform bootstrap process?
- How does the platform bootstrap process work?
---
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
title: Prepare your provider account
description: Understand the requisites to be completed for having the provider account ready to build the cloud-native developer platform.
pipo02mix marked this conversation as resolved.
Show resolved Hide resolved
weight: 10
last_review_date: 2024-04-05
owner:
- https://github.com/orgs/giantswarm/teams/sig-docs
user_questions:
- How do I prepare my provider account for the cloud-native developer platform?
- What do I need to do to prepare my provider account for the cloud-native developer platform?
---

Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
title: Prepare your provider account for AWS
linkTitle: Prepare your AWS account
description: The actions need to be done to prepare your AWS account for starting to build your cloud-native developer platform.
pipo02mix marked this conversation as resolved.
Show resolved Hide resolved
weight: 10
last_review_date: 2024-04-05
owner:
- https://github.com/orgs/giantswarm/teams/sig-docs
user_questions:
- How do I prepare my AWS account for the cloud-native developer platform?
- What do I need to do to prepare my AWS account for the cloud-native developer platform?
---

Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
title: Prepare your provider account for Azure
linkTitle: Prepare your Azure account
description: The actions need to be done to prepare your Azure account for starting to build your cloud-native developer platform.
weight: 20
last_review_date: 2024-04-05
owner:
- https://github.com/orgs/giantswarm/teams/sig-docs
user_questions:
- How do I prepare my Azure account for the cloud-native developer platform?
- What do I need to do to prepare my Azure account for the cloud-native developer platform?
---

Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
title: Prepare your provider account for VMware Cloud Director
linkTitle: Prepare your VCD account
description: The actions need to be done to prepare your VMware installation for starting to build your cloud-native developer platform.
weight: 10
last_review_date: 2024-04-05
owner:
- https://github.com/orgs/giantswarm/teams/sig-docs
user_questions:
- How do I prepare my VMware Cloud Director account for the cloud-native developer platform?
- What do I need to do to prepare my VCD account for the cloud-native developer platform?
---

Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
title: Prepare your provider account for VMware vSphere
linkTitle: Prepare your vSphere account
description: The actions need to be done to prepare your VMware installation for starting to build your cloud-native developer platform.
weight: 10
last_review_date: 2024-04-01
owner:
- https://github.com/orgs/giantswarm/teams/sig-docs
user_questions:
- How do I prepare my VMware vSphere account for the cloud-native developer platform?
- What do I need to do to prepare my VMware vSphere account for the cloud-native developer platform?
---

Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
---
title: Expose your app to the internet
description: Use the platform capabilities to expose your application to the internet.
pipo02mix marked this conversation as resolved.
Show resolved Hide resolved
weight: 60
last_review_date: 2024-04-05
owner:
- https://github.com/orgs/giantswarm/teams/sig-docs
user_questions:
- How does basic connectivity work in the platform?
- What are the options for service connectivity in the platform?
---

<!--
Explain how basic connectivity works (private vs public) through an example
Topics
- Private connectivity
- Public connectivity
- Default network policies
- Ingress and egress

Maybe example of an application that needs to connect to a database to show how it works
pipo02mix marked this conversation as resolved.
Show resolved Hide resolved
-->
Loading