ESC: Review ESC docs/products to build on ontology of concepts and a content plan

[thoward]

The goal of this project is to start defining an ontology for the ESC products and docs, and figure out where we have coverage of the various concepts in which pages/UX, etc.

For example, environment tagging is a concept which is available in numerous places:

• the "Environment Tags" tab in the Pulumi Cloud ESC integration UX
• the ESC CLI via esc env tag ... commands
• mentioned in two docs 1 2
• available in the Python SDK but not documented in the Python SDK documentation pages
• Mentioned as part of this blog post

One thing that jumps out at me from that brief list is that we need to document environment tagging in the SDK docs and need to create a concept page for environment tagging. For example, if I wanted to delete a tag from the SDK, looking at docs, I get no help. Instead I need to read the ESC Python SDK code and there I will find a method client.delete_environment_tag(...).

This project will start by looking through all of these sources (docs, esc cli, esc cloud, esc sdk, blogs) and determining the full list of concepts that ESC covers, and then for each concept see where it is represented in all those tools. Then, a Concepts page should be made for it, with a full description and links out to the various places where the concept is manifested (e.g. esc CLI command docs, esc cloud docs, related blog posts, tutorials, examples, video demos, etc).

This ticket covers the first step: extracting and cataloging all of these product concepts, and building an IA plan for how to represent every concept somewhere in the docs, and building a todo list of content that needs to be created/updated.

The first step/artifact of this process will be making a spreadsheet that lists every documentation page and has a wide/sparse table of concepts (one per column), essentially tagging every page with the concepts within it. Then, take that list of concepts and pivot and aggregate the tag on concept tag to get a list of concept->pages. Then build an ESC Concepts Google Doc, then a ESC Content Plan Google Doc based on that, and eventually, create issues for everything that needs to be written and link into that doc.