ESC: Review ESC docs/products to build on ontology of concepts and a content plan #12865
Labels
area/docs
Improvements or additions to documentation
kind/documentation
Improvements or additions to documentation
kind/task
Work that's part of an ongoing epic
p2
Bugs that aren't P1s but should be done within the quarter
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:
esc env tag ...
commandsOne 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.
The text was updated successfully, but these errors were encountered: