From 32ebaf0cf111bae9baf7a1b0c04ac028760c7cea Mon Sep 17 00:00:00 2001 From: SloaneTribble <100537368+SloaneTribble@users.noreply.github.com> Date: Mon, 1 Jul 2024 13:17:30 -0700 Subject: [PATCH] feat: A few last fixes (#554) * feat: A few last fixes * chore: Match capitalization for all exercise titles --- docs/9-platform-engineering/9.1-backstage.md | 6 +++--- docs/9-platform-engineering/9.1.1-software-catalog.md | 8 ++++---- docs/9-platform-engineering/9.1.2-techdocs.md | 4 ++-- docs/README.md | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/9-platform-engineering/9.1-backstage.md b/docs/9-platform-engineering/9.1-backstage.md index d0957222..7b4c58f5 100644 --- a/docs/9-platform-engineering/9.1-backstage.md +++ b/docs/9-platform-engineering/9.1-backstage.md @@ -29,13 +29,13 @@ docs/9-platform-engineering/9.1-backstage.md: # Backstage -Platform teams are responsible for managing an organization's IDP. As mentioned in the overview section this software can be an API, CLI, or GUI but needs to offer teams self-service tools that adhere to the companies best practices and standards. +Platform teams are responsible for managing an organization's IDP. As mentioned in the overview section this software can be an API, CLI, or GUI but needs to offer teams self-service tools that adhere to the company's best practices and standards. In March 2020 Spotify open sourced their internal developer platform Backstage and donated the project to the Cloud Native Computing Foundation (CNCF). Backstage is a web app that is designed to serve as a 'one stop shop' for all your developer needs. Through its key features of the Software Catalog, Templates, and TechDocs users can get a detailed overview of an organization's technology landscape, easily discover internal projects and documentation, and use a simplified process to create new projects that adhere to the company's standards. ## Backstage's Design -Backstage is a monorepo React application that is written in TypeScript. Backstage is constructed out of three parts. +Backstage is a monorepo React application that is written in TypeScript, and is constructed out of three parts. ![Parts of backstage](https://backstage-spotify-com.spotifycdn.com/_next/static/media/IMG_key_terms.72c69cd1.png ':class=img-center :alt=parts of backstage') @@ -68,7 +68,7 @@ a GitHub org to play around with. Each person going through the bootcamp will ne 1. Follow [GitHubs docs](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch) and create a new Organization (Free) -### Exercise 2: Stand up local instance of Backstage +### Exercise 2: Stand up a Local Instance of Backstage 1. Follow Backstage's official [Getting Started](https://backstage.spotify.com/learn/standing-up-backstage/standing-up-backstage/1-intro/) guide > Skip setting up the PostgresSQL instance diff --git a/docs/9-platform-engineering/9.1.1-software-catalog.md b/docs/9-platform-engineering/9.1.1-software-catalog.md index 36e2cc55..f6e64c04 100644 --- a/docs/9-platform-engineering/9.1.1-software-catalog.md +++ b/docs/9-platform-engineering/9.1.1-software-catalog.md @@ -45,7 +45,7 @@ To solve this problem, Spotify created Backstage, central to which is the Softwa Please read more about it on the [Backstage website](https://backstage.io/docs/features/software-catalog/). ![backstage software catalog](./img9/software-catalog.png ':class=img-center :alt= Backstage Software Catalog') -### Exercise 1: Register an entity to Backstage +### Exercise 1: Register an Entity to Backstage In Backstage, entities represent different types of resources within your system. They are defined using YAML files and registered in the Backstage catalog. Each entity type has a specific purpose and schema. @@ -55,7 +55,7 @@ In Backstage, entities represent different types of resources within your system 2. Continue following the above guide to manually register a component entity to your Backstage instance. *You may find it helpful for future exercises to take note of the information that is provided alongside your components in the UI, and consider where it comes from.* -### Exercise 2: Configure automatic catalog ingestion +### Exercise 2: Configure Automatic Catalog Ingestion While manually registering entities is fairly straightforward, it wouldn't make much sense to do this for a system made up of any more than a few components because it would quickly become tedious and time-consuming. Thankfully there is a way to automate this process. We can set up Backstage to periodically inspect a given location, such as GitHub, for information that it can use to automatically generate these entities. @@ -63,7 +63,7 @@ While manually registering entities is fairly straightforward, it wouldn't make ?> See [GitHub Discovery](https://backstage.io/docs/integrations/github/discovery/) for a useful guide. -### Exercise 3: Generate a dependency graph +### Exercise 3: Generate a Dependency Graph Hopefully you enjoyed the contrast between manually and automatically registering entities. In a similar vein, another useful feature of Backstage is its ability to leverage `catalog-info.yaml` files to automatically generate dependency graphs depicting the relationship between entities in a software ecosystem. The visual aid provided by these graphs can help users quickly understand complex systems. For example, if a developer needs to make a change to a particular service, they can look at that service's dependency graph to know what (and who) else might be affected by such a change. @@ -71,7 +71,7 @@ Hopefully you enjoyed the contrast between manually and automatically registerin 2. Add or modify each repo's `catalog-info.yaml` to define its relationship to the other repo. In other words, we want to be sure that each entity references the other. 3. Verify that within your Backstage instance, each of the two entities' dependency graphs shows a relation to the other entity. -### Exercise 4: Generate an OpenAPI definition +### Exercise 4: Generate an OpenAPI Definition The OpenAPI Specifications provide a formal standard for describing HTTP APIs. Following this standard provides many advantages, including helping people to systematically understand how a given API works on its own and in relation to other APIs, and allowing client code to be automatically generated which can correctly interact with the API. diff --git a/docs/9-platform-engineering/9.1.2-techdocs.md b/docs/9-platform-engineering/9.1.2-techdocs.md index c7c2bb87..9595a41d 100644 --- a/docs/9-platform-engineering/9.1.2-techdocs.md +++ b/docs/9-platform-engineering/9.1.2-techdocs.md @@ -3,7 +3,7 @@ docs/9-platform-engineering/9.1.2-techdocs.md: category: TechDocs estReadingMinutes: 10 exercises: - - name: Enable documentation for an already existing entity + - name: Enable Documentation for an Existing Entity description: | This exercise instructs students to add the bare minimum amount of files needed for their Backstage instance to generate an MkDocs site and associate it with an entity in their Software Catalog. Extra credit is offered for studying Backstage's ability to search within TechDocs stored in the Catalog -- the basic setup we point students towards in this exercise can lead to a search-related bug which is valuable for understanding the different ways Backstage can be configured to manage TechDocs. estMinutes: 40 @@ -20,7 +20,7 @@ This solution is built on top of the *[docs like code approach](https://www.docs Backstage enables the *docs like code approach* by providing tools that can automatically generate an easy-to-navigate documentation website and associate it with one or more entities in a Software Catalog. This can be achieved in multiple ways -- for example, you can [set up automated documentation with your Software Templates](https://backstage.io/docs/features/techdocs/how-to-guides/#how-to-add-the-documentation-setup-to-your-software-templates) so that any Software Templates built on your Backstage instance will come with an associated docs website. You can also [configure CI/CD to generate and publish TechDocs sites](https://backstage.io/docs/features/techdocs/configuring-ci-cd). -### Exercise: Enable documentation for an already existing entity +### Exercise: Enable Documentation for an Existing Entity While TechDocs can be used in a variety of ways, we will start with something simple. diff --git a/docs/README.md b/docs/README.md index ee66a773..908298ce 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1111,7 +1111,7 @@ docs/9-platform-engineering/9.1.2-techdocs.md: category: TechDocs estReadingMinutes: 10 exercises: - - name: Enable documentation for an already existing entity + - name: Enable Documentation for an Existing Entity description: > This exercise instructs students to add the bare minimum amount of files needed for their Backstage instance to generate an MkDocs site and