From 64bd85724fb70dc6320c6131de34403d7cc053d0 Mon Sep 17 00:00:00 2001 From: David Welsch Date: Mon, 29 Apr 2024 11:37:45 -0700 Subject: [PATCH 01/10] Updated tech doc analysis process. Added new analysis templates. Renamed directories to better reflect their contents. Rewrote README files. Signed-off-by: David Welsch Signed-off-by: Patrice Chalin --- README.md | 27 +- TechDoc-Assistance-Program.md | 62 +++ {assessments => analysis}/0001-contour.md | 0 .../0002-notary-project.md | 0 {assessments => analysis}/0003-krator.md | 0 {assessments => analysis}/0004-tremor.md | 0 {assessments => analysis}/0005-fluxcd.md | 0 {assessments => analysis}/0006-gateway-api.md | 0 {assessments => analysis}/0007-porter.md | 0 .../0008-backstage/README.md | 0 .../0008-backstage/backstage-analysis.md | 0 .../0008-backstage/backstage-doc-survey.csv | 370 +++++++++--------- .../0008-backstage/backstage-glossary.md | 0 .../backstage-implementation.md | 0 .../backstage-insights-summary.md | 0 .../0008-backstage/backstage-issues.md | 0 .../0008-backstage/user-roles.md | 0 .../0009-in-toto/README.md | 0 .../0009-in-toto/in-toto-analysis.md | 0 .../0009-in-toto/in-toto-doc-issues.md | 0 .../0009-in-toto/in-toto-implementation.md | 0 .../0009-in-toto/survey-of-existing-doc.md | 0 {assessments => analysis}/0010-etcd/README.md | 0 .../0010-etcd/etcd-analysis.md | 0 .../0010-etcd/etcd-implementation.md | 0 .../0010-etcd/etcd-issues.md | 0 {assessments => analysis}/0011-keda/README.md | 0 .../0011-keda/keda-analysis.md | 0 .../0011-keda/keda-implementation.md | 0 .../0011-keda/keda-issues.md | 0 analysis/README.md | 48 +++ .../New CNCF tech doc artifacts.md | 54 +++ .../analysis-tools}/criteria.md | 0 .../analysis-tools}/howto.md | 0 .../analysis-tools}/template.md | 0 {docs => resources}/README.md | 0 {docs => resources}/analytics.md | 0 {docs => resources}/hugo-and-docsy.md | 0 .../images/folder-based-etcd.png | Bin .../images/subdomain-based-k8s.png | Bin {docs => resources}/localization/README.md | 0 {docs => resources}/netlify-domains-setup.md | 0 {docs => resources}/repo-setup.md | 0 .../searching-documentation.md | 0 {docs => resources}/services.md | 0 .../versioning-documentation.md | 0 .../website-guidelines-checklist.md | 0 47 files changed, 372 insertions(+), 189 deletions(-) create mode 100644 TechDoc-Assistance-Program.md rename {assessments => analysis}/0001-contour.md (100%) rename {assessments => analysis}/0002-notary-project.md (100%) rename {assessments => analysis}/0003-krator.md (100%) rename {assessments => analysis}/0004-tremor.md (100%) rename {assessments => analysis}/0005-fluxcd.md (100%) rename {assessments => analysis}/0006-gateway-api.md (100%) rename {assessments => analysis}/0007-porter.md (100%) rename {assessments => analysis}/0008-backstage/README.md (100%) rename {assessments => analysis}/0008-backstage/backstage-analysis.md (100%) rename {assessments => analysis}/0008-backstage/backstage-doc-survey.csv (99%) rename {assessments => analysis}/0008-backstage/backstage-glossary.md (100%) rename {assessments => analysis}/0008-backstage/backstage-implementation.md (100%) rename {assessments => analysis}/0008-backstage/backstage-insights-summary.md (100%) rename {assessments => analysis}/0008-backstage/backstage-issues.md (100%) rename {assessments => analysis}/0008-backstage/user-roles.md (100%) rename {assessments => analysis}/0009-in-toto/README.md (100%) rename {assessments => analysis}/0009-in-toto/in-toto-analysis.md (100%) rename {assessments => analysis}/0009-in-toto/in-toto-doc-issues.md (100%) rename {assessments => analysis}/0009-in-toto/in-toto-implementation.md (100%) rename {assessments => analysis}/0009-in-toto/survey-of-existing-doc.md (100%) rename {assessments => analysis}/0010-etcd/README.md (100%) rename {assessments => analysis}/0010-etcd/etcd-analysis.md (100%) rename {assessments => analysis}/0010-etcd/etcd-implementation.md (100%) rename {assessments => analysis}/0010-etcd/etcd-issues.md (100%) rename {assessments => analysis}/0011-keda/README.md (100%) rename {assessments => analysis}/0011-keda/keda-analysis.md (100%) rename {assessments => analysis}/0011-keda/keda-implementation.md (100%) rename {assessments => analysis}/0011-keda/keda-issues.md (100%) create mode 100644 analysis/README.md create mode 100644 analysis/analysis-tools/New CNCF tech doc artifacts.md rename {assessments => analysis/analysis-tools}/criteria.md (100%) rename {assessments => analysis/analysis-tools}/howto.md (100%) rename {assessments => analysis/analysis-tools}/template.md (100%) rename {docs => resources}/README.md (100%) rename {docs => resources}/analytics.md (100%) rename {docs => resources}/hugo-and-docsy.md (100%) rename {docs => resources}/images/folder-based-etcd.png (100%) rename {docs => resources}/images/subdomain-based-k8s.png (100%) rename {docs => resources}/localization/README.md (100%) rename {docs => resources}/netlify-domains-setup.md (100%) rename {docs => resources}/repo-setup.md (100%) rename {docs => resources}/searching-documentation.md (100%) rename {docs => resources}/services.md (100%) rename {docs => resources}/versioning-documentation.md (100%) rename {docs => resources}/website-guidelines-checklist.md (100%) diff --git a/README.md b/README.md index 6c7bbab..28634b3 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,27 @@ -# CNCF TechDocs office hours +# CNCF TechDocs -This repository holds team information and meeting notes for tech docs office hours. +This repository holds resources provided by the CNCF Technical Documentation team. The repo contains the following directories: + +- `analysis` contains instructions, templates, and criteria for requesting and performing an analysis of an OSS project's website and technical documentation. Completed analyses are stored here as well. +- `resources` contains information that OSS teams can use to set up a documentation project as suggested by the Tech Docs team. ## CNCF TechDocs team +The full-time staff of the CNCF Tech Docs team is: + GitHub ID | Role ---|--- [@chalin](https://github.com/chalin) | Senior technical writer [@nate-double-u](https://github.com/nate-double-u) | Developer advocate & technical writer [@thisisobate](https://github.com/thisisobate) | Developer advocate + + +Various consultants and volunteers also contribute to CNCF Tech Docs projects. + ## Office hours -The CNCF tech docs team generally holds office hours on the [fourth Wednesday of every month at 8am Pacific time](https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours). +The CNCF tech docs team holds office hours on the [fourth Wednesday of every month at 8am Pacific time](https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours). Office hours started on 30 September, 2020. @@ -24,4 +33,14 @@ Zoom link: https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872?pas We store ongoing meeting notes in a [Google doc](https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/). - +## The Technical Documentation Assistance Program + +The CNCF Tech Doc team has created a program to assist CNCF-affiliated projects in creating effective documentation. [`TechDoc-Assistance-Program.md`](./TechDoc%20Assistance%20Program%20Outline.md) contains an outline of this program. + +Project maintainers are asked to understand that: +- Project documentation resources are *always* underestimated. +- Documentation is as much a real part of a project as code. +- Effective documentation requires a real commitment of resources. +- The TechDoc Assistance Program exists to help maintainers allocate these resources effectively, but cannot write documentation for you or 'fix' documentation problems. + +We're passionate about good documentation and we want to help your project succeed. Please work with us by taking this part of your project seriously. diff --git a/TechDoc-Assistance-Program.md b/TechDoc-Assistance-Program.md new file mode 100644 index 0000000..785664c --- /dev/null +++ b/TechDoc-Assistance-Program.md @@ -0,0 +1,62 @@ +# Technical Documentation Assistance Program + +This document outlines the Cloud Native Computing Foundation (CNCF) Technical Documentation Assistance Program (the Program), a service offered by CNCF Tech Docs for evaluating and improving an OSS project's technical documentation. The process is designed to: + +1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level]. (Often, documentation help is requested when a project requests promotion to a new maturity level.) +1. Recommend changes that will reduce the gap between the documentation and the maturity of the overall project. +1. Expand on the recommended changes in an implementation plan. +1. Break down the implementation into a documentation project backlog comprising an Issues (in GitHub) list. +1. Support the project team's contributors in taking up and completing the issue backlog items. +1. Leave the project team with an improved understanding and skill base for improving and maintaining the project documentation. + +This outline is a working document that presents current aspirations for the Program. It describes both existing elements of the Program and elements that are under discussion. All elements described are existing unless indicated by **TBD**. + +## Phase 0: Training + +Some level of familiarity with the technical documentation process is required to: + +- Work effectively with technical writers +- Draft technical documentation (for non-writers) +- Improve the chances of a good outcome from the Tech Doc Assistance Program + +For this reason, CNCF offers free training on documentation essentials for project contributors and maintainers. To get the most from the Technical Documentation Assistance Program, project contributors should do the training *before* engaging a documentation specialist to complete the documentation analysis. + +The training program consists of the following online courses. Anyone can sign up for and complete the courses at their own pace. + +1. Open Source Doc Essentials LFC111 +1. + +## Phase 1: Documentation Analysis + +A technical writer (on CNCF staff or on contract) analyzes the documentation. Based on the standards developed by the CNCF Tech Docs program, the writer: + +1. Estimates the maturity level of the documentation compared to the current or desired maturity level of the software project, based on a number of criteria in three categories, using a rubric developed by CNCF. The categories are: + 1. Project documentation: The end-user documentation for the project's work product, typically (but not always) an application, API, protocol, or some other software product. + 1. Contributor documentation: Documentation about the project, aimed at project contributors and describing procedures, infrastructure, and customs for doing project work. This includes artifacts that define procedures and governance; recruit, orient, and train project contributors; and name responsible parties (project leaders, often generically called *maintainers*). + 1. Website: The technical infrastructure behind the documentation and the project's web presence, including website generation, versioning, SEO, analytics, and security. +1. Collaborates with project leadership to identify user roles and objectives for software users. If leadership +1. Proposes changes, if necessary, to the organization and content of the documentation to close gaps with the proposed maturity level. + +## Phase 2: Issues + +Once a high-level improvement plan has been written and approved, the tech writer: + +1. Analyzes the proposed changes to create a roadmap to move the project toward the proposed level. +2. Creates issues for specific writing assignments and other tasks to improve the documentation. + +The issues are graded on two axes: + +- Impact: How important the issue is to 1) improving the doc effectiveness and 2) moving the doc toward the desired maturity level. +- Effort: Amount of work the issue is estimated to require to complete. This includes primarily the work of writers and editors, but also SME discussion, review, and approval. + +Of course, it's recommended that the project prioritize higher impact and lower effort issues first. + +## Phase 3: Implementation + +Community members work on the issues created in the previous phase. Ideally, tech writers are available to advise contributors and edit work, especially if the contributing community members are not trained technical writers. + +## Phase 4: Impact Analysis + +To gauge the effectiveness of the documentation effort, we recommend that the project track the documentation issues. Projects are encouraged to collect further metrics on documentation effectiveness. At a minimum though, tracking the issues should provide a guide to progress on leveling the documentation maturity to that of the project. + + diff --git a/assessments/0001-contour.md b/analysis/0001-contour.md similarity index 100% rename from assessments/0001-contour.md rename to analysis/0001-contour.md diff --git a/assessments/0002-notary-project.md b/analysis/0002-notary-project.md similarity index 100% rename from assessments/0002-notary-project.md rename to analysis/0002-notary-project.md diff --git a/assessments/0003-krator.md b/analysis/0003-krator.md similarity index 100% rename from assessments/0003-krator.md rename to analysis/0003-krator.md diff --git a/assessments/0004-tremor.md b/analysis/0004-tremor.md similarity index 100% rename from assessments/0004-tremor.md rename to analysis/0004-tremor.md diff --git a/assessments/0005-fluxcd.md b/analysis/0005-fluxcd.md similarity index 100% rename from assessments/0005-fluxcd.md rename to analysis/0005-fluxcd.md diff --git a/assessments/0006-gateway-api.md b/analysis/0006-gateway-api.md similarity index 100% rename from assessments/0006-gateway-api.md rename to analysis/0006-gateway-api.md diff --git a/assessments/0007-porter.md b/analysis/0007-porter.md similarity index 100% rename from assessments/0007-porter.md rename to analysis/0007-porter.md diff --git a/assessments/0008-backstage/README.md b/analysis/0008-backstage/README.md similarity index 100% rename from assessments/0008-backstage/README.md rename to analysis/0008-backstage/README.md diff --git a/assessments/0008-backstage/backstage-analysis.md b/analysis/0008-backstage/backstage-analysis.md similarity index 100% rename from assessments/0008-backstage/backstage-analysis.md rename to analysis/0008-backstage/backstage-analysis.md diff --git a/assessments/0008-backstage/backstage-doc-survey.csv b/analysis/0008-backstage/backstage-doc-survey.csv similarity index 99% rename from assessments/0008-backstage/backstage-doc-survey.csv rename to analysis/0008-backstage/backstage-doc-survey.csv index c23af5c..775fe92 100644 --- a/assessments/0008-backstage/backstage-doc-survey.csv +++ b/analysis/0008-backstage/backstage-doc-survey.csv @@ -1,185 +1,185 @@ -Title,URL,Doc Type,User Role,Use Case,Doc Suite Position,Comment -Overview,,,,,, -What is Backstage?,https://backstage.io/docs/overview/what-is-backstage,concept,adopter,decision,Technical Overview,Introductory -Architecture overview,https://backstage.io/docs/overview/architecture-overview,concept,administrator,deployment,Architecture Overview,"Substantial, in-depth view of architecture" -Roadmap,https://backstage.io/docs/overview/roadmap,concept,administrator,"deployment, maintenance",Release Notes,Should be updated frequently; move to release notes -Vision,https://backstage.io/docs/overview/vision,concept,"contributor, adopter","strategy, sales",White Paper,"Short, high-level statement of vision." -The Spotify Story,https://backstage.io/docs/overview/background,concept,"contributor, adopter","strategy, sales",White Paper,Background info. Move to website. -Strategies for adopting,https://backstage.io/docs/overview/adopting,concept,adopter,decision,Overview,"Would be useful in adoption go/no-go decisions, and in adoption/deployment/configuration." -Release and Versioning Policy,https://backstage.io/docs/overview/versioning-policy,concept,"contributor, adopter","contribute, maintenance","Release Notes, Contributor Instructions", -Backstage Threat Model,https://backstage.io/docs/overview/threat-model,concept,administrator,deployment,"Architecture Overview, Installation Guide",Required by admin to set up security posture -Support and community,https://backstage.io/docs/overview/support,reference,any,"support, decision, contrib","RN, FAQ, KB, Overviews",Should be available to any interested user from almost anywhere -Backstage Glossary,https://backstage.io/docs/overview/glossary,reference,any,any,KB,"Should be available generally, esp. to new users" -Logo assets,https://backstage.io/docs/overview/logos,reference,"contributor, adopter",contribute,,Reference info for contributing designer -Getting Started,,,,,, -Getting Started,https://backstage.io/docs/getting-started/,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Installation instructions -Getting Started configuring Backstage,https://backstage.io/docs/getting-started/configuration,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide; Getting Started Guide","Split: Configuring database, authentication (installation); Creating your first components (getting started)" -Create an App,https://backstage.io/docs/getting-started/create-an-app,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","How to set up an instance. Might need two setup procedures, one for users and one for admins." -Configuring App with plugins,https://backstage.io/docs/getting-started/configure-app-with-plugins,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Should go in a chapter of the install guide devoted to installing existing plugins -Customize the look-and-feel of your App,https://backstage.io/docs/getting-started/app-custom-theme,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Should be a chapter of the install guide -Backstage homepage - Setup and Customization,https://backstage.io/docs/getting-started/homepage,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide", -Keeping Backstage Updated,https://backstage.io/docs/getting-started/keeping-backstage-updated,task,administrator,"installation, setup, config",IS&C; RN,Upgrade procedures in admin guide; particular upgrades in release notes -Key Concepts,https://backstage.io/docs/getting-started/concepts,reference,administrator,,,This is a list of software dependencies. Needed by admin. Upgrades needed by each release in RN. -Contributors,https://backstage.io/docs/getting-started/contributors,task,contributor,contribute,Contributor setup guide,"Contributor guide can be limited to GitHub, or a separate contributor guide put on the website" -Getting Involved,https://backstage.io/docs/getting-started/getting-involved,reference,contributor,contribute,Contributor overview,This material belongs in the intro to a contributor guide -Backstage Project Structure,https://backstage.io/docs/getting-started/project-structure,reference,contributor,contribute,Contributor reference,"Structure of the GitHub repo, annotated. Reference for contributors." -Local Development,,,,,, -Overview,https://backstage.io/docs/local-dev/cli-overview,concept,administrator,deployment,Architecture Overview,"This is part of the architecture overview, a discussion of the components of the CLI" -Build System,https://backstage.io/docs/local-dev/cli-build-system,concept,administrator,deployment,Architecture Overview,Description of how the Build system works; belongs in the Architecture Overview -Commands,https://backstage.io/docs/local-dev/cli-commands,reference,administrator; user,use,API Reference,"This is a command reference for the CLI, which seems to be a tool for doing builds of components in Backstage" -Linking in Local Packages,https://backstage.io/docs/local-dev/linking-local-packages,task,user,use,Recipe,This is a technique for testing a build. Goes in a recipe book or use and testing guide. -Debugging Backstage,https://backstage.io/docs/local-dev/debugging,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Description of how to change the logging level in Backstage. -Core Features,,,,,, -Overview,https://backstage.io/docs/features/software-catalog/,task,user,use,User Guide,Basic catalog tasks. Also a short intro to the catalog (conceptual). -The Life of an Entity,https://backstage.io/docs/features/software-catalog/life-of-an-entity,concept,administrator; user,deployment,Architecture Overview,Detailed description of data ingestion when importing an entity. -Catalog Configuration,https://backstage.io/docs/features/software-catalog/configuration,concept,administrator; user,deployment,Architecture Overview,Additional information for ingesting entities -System Model,https://backstage.io/docs/features/software-catalog/system-model,concept,user,use,User Guide,Describes the model behind various entities. Some of this could go in the Knowledge Base as well maybe. -YAML File Format,https://backstage.io/docs/features/software-catalog/descriptor-format,reference,user,use,User Guide,"Reference to entity descriptors, with examples in JSON." -Entity References,https://backstage.io/docs/features/software-catalog/references,reference,user,use,User Guide,Description of how entities reference other entities -Well-known Annotations,https://backstage.io/docs/features/software-catalog/well-known-annotations,reference,user,use,User Guide,More on entities -Well-known Relations,https://backstage.io/docs/features/software-catalog/well-known-relations,reference,user,use,User Guide,More on entities -Well-known Statuses,https://backstage.io/docs/features/software-catalog/well-known-statuses,reference,user,use,User Guide,More on entities -Extending the model,https://backstage.io/docs/features/software-catalog/extending-the-model,reference,user,use,User Guide,More on entities -External integrations,https://backstage.io/docs/features/software-catalog/external-integrations,reference,user,use,User Guide,More on entities -Catalog Customization,https://backstage.io/docs/features/software-catalog/catalog-customization,task,administrator,deployment,"Installation, Setup, and Config Guide",How to customize the entity display page. A recipe for the site admin -API,https://backstage.io/docs/features/software-catalog/software-catalog-api,reference,administrator; user,use,API Reference,The Entity API. Could be teased apart into a true reference and a set of recipes. -Creating the Catalog Graph,https://backstage.io/docs/features/software-catalog/creating-the-catalog-graph,reference,user,use,User Guide,Describes the catalog model and what is displayed in the UI -Overview,https://backstage.io/docs/features/kubernetes/,concept,user,use,Kubernetes plugin guide,Intro to the 2 Kubernetes plugins -Installation,https://backstage.io/docs/features/kubernetes/installation,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Could go in the main install guide or in a separate k8s guide -Configuration,https://backstage.io/docs/features/kubernetes/configuration,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide","Continuation of k8s install instructions, but contains mostly descriptions of the config settings" -Kubernetes Authentication,https://backstage.io/docs/features/kubernetes/authentication,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Describes how to authenticate k8s on various services. -Troubleshooting,https://backstage.io/docs/features/kubernetes/troubleshooting,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",What to do if k8s doesn’t show up as a service entity -Proxy,https://backstage.io/docs/features/kubernetes/proxy,task,"contributor, admin","installation, setup, config","Installation, Setup, and Config Guide",How to set up a k8s proxy endpoint. Known limitation should be moved to a release note. -Overview,https://backstage.io/docs/features/software-templates/,task,administrator; user,getting started,Getting Started Guide (“Hello World”),“Disable Register Existing Component button” is an admin task that should be in the config documentation -Configuration,https://backstage.io/docs/features/software-templates/configuration,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to configure a template -Adding your own Templates,https://backstage.io/docs/features/software-templates/adding-templates,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to add a template -Writing Templates,https://backstage.io/docs/features/software-templates/writing-templates,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",The anatomy of a template and how to write one. -Input Examples,https://backstage.io/docs/features/software-templates/input-examples,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Anatomy of template input components. Could be a mini-cookbook or a section of the config instructions for Templates -Builtin actions,https://backstage.io/docs/features/software-templates/builtin-actions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Describes how to migrate a fetch action from a one fetch action to another. Not clear why this is important; should give some more context. -Writing Custom Actions,https://backstage.io/docs/features/software-templates/writing-custom-actions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to create a custom template action -Writing Custom Field Extensions,https://backstage.io/docs/features/software-templates/writing-custom-field-extensions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",More on customizing templates: creating your own field types -Writing custom step layouts,https://backstage.io/docs/features/software-templates/writing-custom-step-layouts,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Still more on customizing templates: creating your own step layouts -Authorizing parameters steps and actions,https://backstage.io/docs/features/software-templates/authorizing-parameters-steps-and-actions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Authorization in custom templates -Experimental: Testing out the alpha Scaffolder plugin,https://backstage.io/docs/features/software-templates/testing-scaffolder-alpha,task,administrator,"installation, setup, config",Release Notes,Information about features that are in flux or still in development should have their own documentation separate from the production system. The feature should be described in the Release Notes. -Migrating to v1beta3 templates,https://backstage.io/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3,,administrator,"installation, setup, config",Release Notes,Information about features that are in flux or still in development should have their own documentation separate from the production system. The feature should be described in the Release Notes. -Overview,https://backstage.io/docs/features/search/,concept,administrator; user,use,User Guide,"Intro to the search feature, including its configurability as a plugin" -Getting Started with Search,https://backstage.io/docs/features/search/getting-started,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Installing and configuring frontend and backend search -Search Concepts,https://backstage.io/docs/features/search/concepts,concept,administrator; user,"deployment, use",Technical Overview,Description of search system components. -Search Architecture,https://backstage.io/docs/features/search/architecture,concept,all,"decision, deployment",Architecture Overview,Description of search architecture -Search Engines,https://backstage.io/docs/features/search/search-engines,concept,administrator; user,deployment,Architecture Overview,Describes search backends available by default -How-To guides,https://backstage.io/docs/features/search/how-to-guides,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to deploy a custom search backend -Overview,https://backstage.io/docs/features/techdocs/,concept,all,"decision, deployment",Architecture Overview,Intro to tech docs feature -Getting Started,https://backstage.io/docs/features/techdocs/getting-started,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide",Install and config instructions for the TechDoc frontend and backend plugins -Concepts,https://backstage.io/docs/features/techdocs/concepts,concept,administrator; user,"deployment, use","Architecture Overview, Installation Guide",Describes the TechDocs plugin component architecture. -TechDocs Addons,https://backstage.io/docs/features/techdocs/addons,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Describes how to install and configure add-ons to the TechDocs plugin -TechDocs Architecture,https://backstage.io/docs/features/techdocs/architecture,concept,administrator; user,deployment,Architecture Overview,TechDocs architecture block diagrams. -Creating and Publishing Documentation,https://backstage.io/docs/features/techdocs/creating-and-publishing,task,user,use,User Guide,How to add existing docs or create a new doc in TechDcos -TechDocs Configuration Options,https://backstage.io/docs/features/techdocs/configuration,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",A description in an example YAML file of the TechDocs configuration parameters. Don’t know if it’s comprehensive or not. -Using Cloud Storage for TechDocs generated files,https://backstage.io/docs/features/techdocs/using-cloud-storage,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up TechDocs on major cloud services -Configuring CI/CD to generate and publish TechDocs sites,https://backstage.io/docs/features/techdocs/configuring-ci-cd,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to automate TechDocs publication in CI/CD -TechDocs CLI,https://backstage.io/docs/features/techdocs/cli,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Reference and how-to information on using the CLI. A bit of a catch-all; should be parceled out in more focused docs. -How-To guides,https://backstage.io/docs/features/techdocs/how-to-guides,task,administrator; user,"deployment, use",Recipe,How-tos for various TechDocs tasks. probably partly redundant with other pages. -Troubleshooting,https://backstage.io/docs/features/techdocs/troubleshooting,task,administrator; user,"deployment, use",Maintenance Guide; User Guide,How to solve several trouble scenarios -FAQ,https://backstage.io/docs/features/techdocs/faqs,concept,administrator; user,"deployment, use",KB,Info about the TechDocs plugin. Probably partly redundant with other pages. -Integrations,,,,,, -Overview,https://backstage.io/docs/integrations/,concept,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Intro to integrations. Needs to be expanded. There are about a dozen listed integrations with common cloud providers and software repos. This could be its own supplement to the installation guide or a chapter or appendix. It's almost certain to be needed for any major installation. -Plugins,,,,,, -Intro to plugins,https://backstage.io/docs/plugins/,concept,administrator,deployment,Architecture Overview,"This introduction needs to be expanded (though that material might exist elsewhere). There are pointers here mostly to contributor actions. ""Contributing a plugin"" needs to be its own separate document on the GitHub site." -Existing plugins,https://backstage.io/docs/plugins/existing-plugins,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",This is a pointer to the plugin catalog. The catalog should be an appendix to the installation and config guide. -Create a Backstage Plugin,https://backstage.io/docs/plugins/create-a-plugin,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",This is actually a brief description of how to install a plugin on an existing Backstage instance. -Plugin Development,https://backstage.io/docs/plugins/plugin-development,concept,"contributor, admin","contribute, maintenance",Contributor reference,A brief outline of how to develop a plugin. Should go in the contributor guide. -Structure of a Plugin,https://backstage.io/docs/plugins/structure-of-a-plugin,reference,"contributor, admin","contribute, maintenance",Contributor reference,Description of the structure of a plugin. -Integrate into the Software Catalog,https://backstage.io/docs/plugins/integrating-plugin-into-software-catalog,task,contributor,contribute,Contributor reference,"Describes how to add a plugin to the entities page on a Backstage instance. Described as ""advanced"" and ""experimental""." -Integrating Search into a plugin,https://backstage.io/docs/plugins/integrating-search-into-plugins,task,contributor,contribute,Contributor reference,Instructions for implementing search in a plugin. -Composability System,https://backstage.io/docs/plugins/composability,concept,contributor,contribute,Contributor reference,How plugins talk to each other using React extension. Contains some instructional code that should be separated into a procedure. -Customization (Experimental),https://backstage.io/docs/plugins/customization,task,"contributor, user","contribute, use","Contributor reference, User guide","How to customize a plugin. Instructions for both contributor (plugin developer) and a short snippet for a developer to use in an existing installation. Labeled ""experimental""." -Plugin Analytics,https://backstage.io/docs/plugins/analytics,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","Conceptual, reference, and (mostly) task information about using a supplied analytics API to collect usage data on Backstage." -Feature Flags,https://backstage.io/docs/plugins/feature-flags,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide","How to set features flags to define plugin behavior, both in plugin code and from the Backstage application." -Proxying,https://backstage.io/docs/plugins/proxying,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up an HTTP proxy to reach backend services from the Backstage frontend -Backend plugins,https://backstage.io/docs/plugins/backend-plugin,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Instructions for an admin to create and configure a backend plugin. This is one of those pieces of content that spans admin and contributor. -Call Existing API,https://backstage.io/docs/plugins/call-existing-api,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide",How to call an arbitrary API from the Backstage frontend -URL Reader,https://backstage.io/docs/plugins/url-reader,task,contributor,contribute,Contributor reference,How to use the Backstage URL reader API to securely read files from a plugin. -Testing with Jest,https://backstage.io/docs/plugins/testing,concept,contributor,contribute,Contributor reference,A description of the infrastructure (Jest) and principles to use when writing unit tests for plugins. -Publish private,https://backstage.io/docs/plugins/publish-private,,,,,"""TODO""" -Add to Marketplace,https://backstage.io/docs/plugins/add-to-marketplace,task,contributor,contribute,Contributor reference,How to add a plugin to the plugin library listed in the documentation -Observability,https://backstage.io/docs/plugins/observability,reference,contributor,contribute,Contributor reference,A brief overview of some logging mechanisms. Covered elsewhere. -Configuration,,,,,, -Static Configuration in Backstage,https://backstage.io/docs/conf/,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. -Reading Backstage Configuration,https://backstage.io/docs/conf/reading,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. -Writing Backstage Configuration Files,https://backstage.io/docs/conf/writing,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. -Defining Configuration for your Plugin,https://backstage.io/docs/conf/defining,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. -Auth and identity,,,,,, -Authentication in Backstage,https://backstage.io/docs/auth/,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","How to configure authentication. There are at least 14 individual pages for various providers giving detailed instructions for these providers: ""https://backstage.io/docs/auth/atlassian/provider"" and so on." -Sign-in Identities and Resolvers,https://backstage.io/docs/auth/identity-resolver,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up identities for authorization. Probably useful to plugin contributors as well. -OAuth and OpenID Connect,https://backstage.io/docs/auth/oauth,concept,"contributor, admin","contribute, maintenance","Contributor reference, User guide",Describes how tokens are used by Backstage for third-party services. Includes a sequence diagram. -OIDC provider from scratch,https://backstage.io/docs/auth/oidc,task,"contributor, admin",contribute,Contributor reference,How to use Open ID Connect (OIDC) to connect to Backstage. -Contributing New Providers,https://backstage.io/docs/auth/add-auth-provider,task,contributor,contribute,Contributor reference,How to add support for a new authentication provider. Recommended solely for contributors. -Service to Service Auth,https://backstage.io/docs/auth/service-to-service-auth,task,contributor,contribute,Contributor reference,How to set up a plugin to authenticate another service or plugin. -Troubleshooting Auth,https://backstage.io/docs/auth/troubleshooting,task,"contributor, admin",contribute,"Installation, Setup, and Config Guide",Troubleshooting various authentication problems. These span development of plugins to administration of Backstage instances. -Glossary,https://backstage.io/docs/auth/glossary,reference,all,any,,A glossary of terms for authentication. -Permissions,,,,,, -Overview,https://backstage.io/docs/permissions/overview,concept,all,deployment,Architecture Overview,"An introduction to authorization in Backstage, with a flow diagram." -Concepts,https://backstage.io/docs/permissions/concepts,reference,"contributor, admin","contribute, maintenance",Contributor reference,A glossary of authorization terms. -Getting Started,https://backstage.io/docs/permissions/getting-started,task,"contributor, admin","contribute, maintenance",Contributor reference,How to set up authorization in a Backstage plugin. -Writing a permission policy,https://backstage.io/docs/permissions/writing-a-policy,task,"contributor, admin","contribute, maintenance",Contributor reference,How to write a permission policy in a Typescript file. -Frontend Integration,https://backstage.io/docs/permissions/frontend-integration,task,"contributor, admin","contribute, maintenance",Contributor reference,An example showing what to do when frontend permission policy needs to be set. -Defining custom permission rules,https://backstage.io/docs/permissions/custom-rules,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up a custom rule outside the context of a plugin. -1. Tutorial setup,https://backstage.io/docs/permissions/plugin-authors/01-setup,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. -2. Adding a basic permission check,https://backstage.io/docs/permissions/plugin-authors/02-adding-a-basic-permission-check,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. -3. Adding a resource permission check,https://backstage.io/docs/permissions/plugin-authors/03-adding-a-resource-permission-check,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. -4. Authorizing access to paginated data,https://backstage.io/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. -5. Frontend Components with Authorization,https://backstage.io/docs/permissions/plugin-authors/05-frontend-authorization,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. -Deployment,,,,,, -Overview,https://backstage.io/docs/deployment/,concept,administrator,deployment,"Installation, Setup, and Config Guide",Introduction to deploying a Backstage instance. -Scaling,https://backstage.io/docs/deployment/scaling,concept,administrator,deployment,"Installation, Setup, and Config Guide",Brief discussion of how to scale Backstage across an org -Docker,https://backstage.io/docs/deployment/docker,task,administrator,deployment,"Installation, Setup, and Config Guide",How to deploy using Docker. -Kubernetes,https://backstage.io/docs/deployment/k8s,task,administrator,deployment,"Installation, Setup, and Config Guide",Fairly extensive instructions on how to deploy Backstage using Docker on Kubernetes -Heroku,https://backstage.io/docs/deployment/heroku,task,administrator,deployment,"Installation, Setup, and Config Guide",Deploying using Heroic -Koyeb,https://backstage.io/docs/deployment/koyeb,task,administrator,deployment,"Installation, Setup, and Config Guide",Deploying using Kobe -AWS Fargate via Flightcontrol,https://backstage.io/docs/deployment/flightcontrol,task,administrator,deployment,"Installation, Setup, and Config Guide",Deploying on AWS using Flightcontrol -Designing for Backstage,,,,,, -Design,https://backstage.io/docs/dls/design,concept,contributor,contribute,Contributor overview,Introduction to the Backstage OSS project. -Component Design Guidelines,https://backstage.io/docs/dls/component-design-guidelines,concept,contributor,contribute,Contributor reference,Visual design guidelines for components -Contributing to Storybook,https://backstage.io/docs/dls/contributing-to-storybook,task,contributor,contribute,Contributor reference,How to add a control to the Backstage Storybook catalog -Figma,https://backstage.io/docs/dls/figma,reference,contributor,contribute,Contributor reference,Link to the Figma component library for Backstage -API Reference,,,,,, -Utility APIs,https://backstage.io/docs/api/utility-apis,task,contributor,contribute,Contributor reference,Describes the infrastructure for creating and using APIs that operate between plugins. -Package Index,https://backstage.io/docs/reference/,reference,contributor,contribute,Contributor reference,A lengthy catalog of APIs -Deprecations,https://backstage.io/docs/api/deprecations,reference,all,any,,Describes deprecated elements in Backstage. Deprecations should be noted in reference material and described in release notes. -Tutorials,,,,,, -Future developer journey,https://backstage.io/docs/tutorials/journey,task,"contributor, admin",contribute,Recipe,"Extended example about a fictional developer adding a new plugin to an installation, then to the project" -Adding Custom Plugin to Existing Monorepo App,https://backstage.io/docs/tutorials/quickstart-app-plugin,task,administrator,deployment,Recipe,How to develop a plugin in an existing Backstage installation (app) -React Router 6.0 Migration,https://backstage.io/docs/tutorials/react-router-stable-migration,task,administrator,"installation, setup, config",Release Notes,"How to upgrade to a newer version of React router. A version-specific procedure that should be hidden from general admin procedures. Should have been a release-specific task, if necessary at all" -Package Role Migration,https://backstage.io/docs/tutorials/package-role-migration,task,administrator,"installation, setup, config",Release Notes,"Another transitional step that should be part of a version upgrade, not a user tutorial." -Migrating away from @backstage/core,https://backstage.io/docs/tutorials/migrating-away-from-core,task,administrator,"installation, setup, config",Release Notes,Another refactoring migration. Remove from tutorials. -Configuring Plugin Databases,https://backstage.io/docs/tutorials/configuring-plugin-databases,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","I could see putting this in a recipe guide or a config guide, plugin-specific or otherwise. Not a tutorial." -Switching Backstage from SQLite to PostgreSQL,https://backstage.io/docs/tutorials/switching-sqlite-postgres,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to change the default DB from SQLite to PostgreSQL. This should be in the basic configuration guide. -Using the Backstage Proxy from Within a Plugin,https://backstage.io/docs/tutorials/using-backstage-proxy-within-plugin,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to access an external API using a proxy. A plugin configuration task. -Migration to Yarn 3,https://backstage.io/docs/tutorials/yarn-migration,task,administrator,deployment,Release Notes,Another release-specific migration. Remove from tutorials. -Architecture Decision Records (ADRs),,,,,, -Overview,https://backstage.io/docs/architecture-decisions/,concept,"contributor, admin",deployment,Architecture Overview,"An intro to architectural decision records (ADRs). Potentially part of an architecture overview. Could be omitted from the user doc altogether, though. Primarily of interest to contributors." -ADR001: Architecture Decision Record (ADR) log,https://backstage.io/docs/architecture-decisions/adrs-adr001,concept,contributor,contribute,Contributor reference,Meta ADR about where to store ADRs. -ADR002: Default Software Catalog File Format,https://backstage.io/docs/architecture-decisions/adrs-adr002,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR003: Avoid Default Exports and Prefer Named Exports,https://backstage.io/docs/architecture-decisions/adrs-adr003,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR004: Module Export Structure,https://backstage.io/docs/architecture-decisions/adrs-adr004,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR005: Catalog Core Entities,https://backstage.io/docs/architecture-decisions/adrs-adr005,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR006: Avoid React.FC and React.SFC,https://backstage.io/docs/architecture-decisions/adrs-adr006,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR007: Use MSW to mock http requests,https://backstage.io/docs/architecture-decisions/adrs-adr007,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR008: Default Catalog File Name,https://backstage.io/docs/architecture-decisions/adrs-adr008,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR009: Entity References,https://backstage.io/docs/architecture-decisions/adrs-adr009,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR010: Use the Luxon Date Library,https://backstage.io/docs/architecture-decisions/adrs-adr010,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR011: Plugin Package Structure,https://backstage.io/docs/architecture-decisions/adrs-adr011,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR012: Use Luxon.toLocaleString and date/time presets,https://backstage.io/docs/architecture-decisions/adrs-adr012,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR013: Proper use of HTTP fetching libraries,https://backstage.io/docs/architecture-decisions/adrs-adr013,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -FAQ,,,,,, -FAQ,https://backstage.io/docs/FAQ,reference,all,any,KB,"This is a fairly robust FAQ. I usually recommend doing away with a FAQ on the grounds that it's a last resort for someone looking for information. Distribute its topics to where they belong in the documentation. Use a knowledge base (similar, but longer-format articles with conceptual information only) for miscellaneous, indexed, conceptual information." -Experimental Backend System,,,,,, -Introduction,https://backstage.io/docs/backend-system/,concept,"contributor, admin",deployment,Contributor reference,"Information about a refactoring of existing functionality should be kept in the developer (contributor) discussion until it is deployed, at which point it should be documented in the release notes. Mentions of timing (""this component is in alpha""; ""currently this works like this""; ""we plan to ..."") should be avoided entirely in the product regular documentation. Version-specific information should be documented at the time of release in the release notes. If the change affects functionality, the new functionality should replace the old in the documentation set starting at the new version of the doc." -Overview,https://backstage.io/docs/backend-system/architecture/index,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" -Services,https://backstage.io/docs/backend-system/architecture/services,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" -Plugins,https://backstage.io/docs/backend-system/architecture/plugins,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" -Extension Points,https://backstage.io/docs/backend-system/architecture/extension-points,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" -Modules,https://backstage.io/docs/backend-system/architecture/modules,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" -Naming Patterns,https://backstage.io/docs/backend-system/architecture/naming-patterns,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" -Accessibility,,,,,, -Backstage Accessibility,https://backstage.io/docs/accessibility/,task,contributor,contribute,Contributor reference,How to incorporate accessibility into contributed software components \ No newline at end of file +Title,URL,Doc Type,User Role,Use Case,Doc Suite Position,Comment +Overview,,,,,, +What is Backstage?,https://backstage.io/docs/overview/what-is-backstage,concept,adopter,decision,Technical Overview,Introductory +Architecture overview,https://backstage.io/docs/overview/architecture-overview,concept,administrator,deployment,Architecture Overview,"Substantial, in-depth view of architecture" +Roadmap,https://backstage.io/docs/overview/roadmap,concept,administrator,"deployment, maintenance",Release Notes,Should be updated frequently; move to release notes +Vision,https://backstage.io/docs/overview/vision,concept,"contributor, adopter","strategy, sales",White Paper,"Short, high-level statement of vision." +The Spotify Story,https://backstage.io/docs/overview/background,concept,"contributor, adopter","strategy, sales",White Paper,Background info. Move to website. +Strategies for adopting,https://backstage.io/docs/overview/adopting,concept,adopter,decision,Overview,"Would be useful in adoption go/no-go decisions, and in adoption/deployment/configuration." +Release and Versioning Policy,https://backstage.io/docs/overview/versioning-policy,concept,"contributor, adopter","contribute, maintenance","Release Notes, Contributor Instructions", +Backstage Threat Model,https://backstage.io/docs/overview/threat-model,concept,administrator,deployment,"Architecture Overview, Installation Guide",Required by admin to set up security posture +Support and community,https://backstage.io/docs/overview/support,reference,any,"support, decision, contrib","RN, FAQ, KB, Overviews",Should be available to any interested user from almost anywhere +Backstage Glossary,https://backstage.io/docs/overview/glossary,reference,any,any,KB,"Should be available generally, esp. to new users" +Logo assets,https://backstage.io/docs/overview/logos,reference,"contributor, adopter",contribute,,Reference info for contributing designer +Getting Started,,,,,, +Getting Started,https://backstage.io/docs/getting-started/,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Installation instructions +Getting Started configuring Backstage,https://backstage.io/docs/getting-started/configuration,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide; Getting Started Guide","Split: Configuring database, authentication (installation); Creating your first components (getting started)" +Create an App,https://backstage.io/docs/getting-started/create-an-app,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","How to set up an instance. Might need two setup procedures, one for users and one for admins." +Configuring App with plugins,https://backstage.io/docs/getting-started/configure-app-with-plugins,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Should go in a chapter of the install guide devoted to installing existing plugins +Customize the look-and-feel of your App,https://backstage.io/docs/getting-started/app-custom-theme,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Should be a chapter of the install guide +Backstage homepage - Setup and Customization,https://backstage.io/docs/getting-started/homepage,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide", +Keeping Backstage Updated,https://backstage.io/docs/getting-started/keeping-backstage-updated,task,administrator,"installation, setup, config",IS&C; RN,Upgrade procedures in admin guide; particular upgrades in release notes +Key Concepts,https://backstage.io/docs/getting-started/concepts,reference,administrator,,,This is a list of software dependencies. Needed by admin. Upgrades needed by each release in RN. +Contributors,https://backstage.io/docs/getting-started/contributors,task,contributor,contribute,Contributor setup guide,"Contributor guide can be limited to GitHub, or a separate contributor guide put on the website" +Getting Involved,https://backstage.io/docs/getting-started/getting-involved,reference,contributor,contribute,Contributor overview,This material belongs in the intro to a contributor guide +Backstage Project Structure,https://backstage.io/docs/getting-started/project-structure,reference,contributor,contribute,Contributor reference,"Structure of the GitHub repo, annotated. Reference for contributors." +Local Development,,,,,, +Overview,https://backstage.io/docs/local-dev/cli-overview,concept,administrator,deployment,Architecture Overview,"This is part of the architecture overview, a discussion of the components of the CLI" +Build System,https://backstage.io/docs/local-dev/cli-build-system,concept,administrator,deployment,Architecture Overview,Description of how the Build system works; belongs in the Architecture Overview +Commands,https://backstage.io/docs/local-dev/cli-commands,reference,administrator; user,use,API Reference,"This is a command reference for the CLI, which seems to be a tool for doing builds of components in Backstage" +Linking in Local Packages,https://backstage.io/docs/local-dev/linking-local-packages,task,user,use,Recipe,This is a technique for testing a build. Goes in a recipe book or use and testing guide. +Debugging Backstage,https://backstage.io/docs/local-dev/debugging,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Description of how to change the logging level in Backstage. +Core Features,,,,,, +Overview,https://backstage.io/docs/features/software-catalog/,task,user,use,User Guide,Basic catalog tasks. Also a short intro to the catalog (conceptual). +The Life of an Entity,https://backstage.io/docs/features/software-catalog/life-of-an-entity,concept,administrator; user,deployment,Architecture Overview,Detailed description of data ingestion when importing an entity. +Catalog Configuration,https://backstage.io/docs/features/software-catalog/configuration,concept,administrator; user,deployment,Architecture Overview,Additional information for ingesting entities +System Model,https://backstage.io/docs/features/software-catalog/system-model,concept,user,use,User Guide,Describes the model behind various entities. Some of this could go in the Knowledge Base as well maybe. +YAML File Format,https://backstage.io/docs/features/software-catalog/descriptor-format,reference,user,use,User Guide,"Reference to entity descriptors, with examples in JSON." +Entity References,https://backstage.io/docs/features/software-catalog/references,reference,user,use,User Guide,Description of how entities reference other entities +Well-known Annotations,https://backstage.io/docs/features/software-catalog/well-known-annotations,reference,user,use,User Guide,More on entities +Well-known Relations,https://backstage.io/docs/features/software-catalog/well-known-relations,reference,user,use,User Guide,More on entities +Well-known Statuses,https://backstage.io/docs/features/software-catalog/well-known-statuses,reference,user,use,User Guide,More on entities +Extending the model,https://backstage.io/docs/features/software-catalog/extending-the-model,reference,user,use,User Guide,More on entities +External integrations,https://backstage.io/docs/features/software-catalog/external-integrations,reference,user,use,User Guide,More on entities +Catalog Customization,https://backstage.io/docs/features/software-catalog/catalog-customization,task,administrator,deployment,"Installation, Setup, and Config Guide",How to customize the entity display page. A recipe for the site admin +API,https://backstage.io/docs/features/software-catalog/software-catalog-api,reference,administrator; user,use,API Reference,The Entity API. Could be teased apart into a true reference and a set of recipes. +Creating the Catalog Graph,https://backstage.io/docs/features/software-catalog/creating-the-catalog-graph,reference,user,use,User Guide,Describes the catalog model and what is displayed in the UI +Overview,https://backstage.io/docs/features/kubernetes/,concept,user,use,Kubernetes plugin guide,Intro to the 2 Kubernetes plugins +Installation,https://backstage.io/docs/features/kubernetes/installation,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Could go in the main install guide or in a separate k8s guide +Configuration,https://backstage.io/docs/features/kubernetes/configuration,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide","Continuation of k8s install instructions, but contains mostly descriptions of the config settings" +Kubernetes Authentication,https://backstage.io/docs/features/kubernetes/authentication,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Describes how to authenticate k8s on various services. +Troubleshooting,https://backstage.io/docs/features/kubernetes/troubleshooting,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",What to do if k8s doesn’t show up as a service entity +Proxy,https://backstage.io/docs/features/kubernetes/proxy,task,"contributor, admin","installation, setup, config","Installation, Setup, and Config Guide",How to set up a k8s proxy endpoint. Known limitation should be moved to a release note. +Overview,https://backstage.io/docs/features/software-templates/,task,administrator; user,getting started,Getting Started Guide (“Hello World”),“Disable Register Existing Component button” is an admin task that should be in the config documentation +Configuration,https://backstage.io/docs/features/software-templates/configuration,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to configure a template +Adding your own Templates,https://backstage.io/docs/features/software-templates/adding-templates,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to add a template +Writing Templates,https://backstage.io/docs/features/software-templates/writing-templates,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",The anatomy of a template and how to write one. +Input Examples,https://backstage.io/docs/features/software-templates/input-examples,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Anatomy of template input components. Could be a mini-cookbook or a section of the config instructions for Templates +Builtin actions,https://backstage.io/docs/features/software-templates/builtin-actions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Describes how to migrate a fetch action from a one fetch action to another. Not clear why this is important; should give some more context. +Writing Custom Actions,https://backstage.io/docs/features/software-templates/writing-custom-actions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to create a custom template action +Writing Custom Field Extensions,https://backstage.io/docs/features/software-templates/writing-custom-field-extensions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",More on customizing templates: creating your own field types +Writing custom step layouts,https://backstage.io/docs/features/software-templates/writing-custom-step-layouts,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Still more on customizing templates: creating your own step layouts +Authorizing parameters steps and actions,https://backstage.io/docs/features/software-templates/authorizing-parameters-steps-and-actions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Authorization in custom templates +Experimental: Testing out the alpha Scaffolder plugin,https://backstage.io/docs/features/software-templates/testing-scaffolder-alpha,task,administrator,"installation, setup, config",Release Notes,Information about features that are in flux or still in development should have their own documentation separate from the production system. The feature should be described in the Release Notes. +Migrating to v1beta3 templates,https://backstage.io/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3,,administrator,"installation, setup, config",Release Notes,Information about features that are in flux or still in development should have their own documentation separate from the production system. The feature should be described in the Release Notes. +Overview,https://backstage.io/docs/features/search/,concept,administrator; user,use,User Guide,"Intro to the search feature, including its configurability as a plugin" +Getting Started with Search,https://backstage.io/docs/features/search/getting-started,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Installing and configuring frontend and backend search +Search Concepts,https://backstage.io/docs/features/search/concepts,concept,administrator; user,"deployment, use",Technical Overview,Description of search system components. +Search Architecture,https://backstage.io/docs/features/search/architecture,concept,all,"decision, deployment",Architecture Overview,Description of search architecture +Search Engines,https://backstage.io/docs/features/search/search-engines,concept,administrator; user,deployment,Architecture Overview,Describes search backends available by default +How-To guides,https://backstage.io/docs/features/search/how-to-guides,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to deploy a custom search backend +Overview,https://backstage.io/docs/features/techdocs/,concept,all,"decision, deployment",Architecture Overview,Intro to tech docs feature +Getting Started,https://backstage.io/docs/features/techdocs/getting-started,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide",Install and config instructions for the TechDoc frontend and backend plugins +Concepts,https://backstage.io/docs/features/techdocs/concepts,concept,administrator; user,"deployment, use","Architecture Overview, Installation Guide",Describes the TechDocs plugin component architecture. +TechDocs Addons,https://backstage.io/docs/features/techdocs/addons,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Describes how to install and configure add-ons to the TechDocs plugin +TechDocs Architecture,https://backstage.io/docs/features/techdocs/architecture,concept,administrator; user,deployment,Architecture Overview,TechDocs architecture block diagrams. +Creating and Publishing Documentation,https://backstage.io/docs/features/techdocs/creating-and-publishing,task,user,use,User Guide,How to add existing docs or create a new doc in TechDcos +TechDocs Configuration Options,https://backstage.io/docs/features/techdocs/configuration,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",A description in an example YAML file of the TechDocs configuration parameters. Don’t know if it’s comprehensive or not. +Using Cloud Storage for TechDocs generated files,https://backstage.io/docs/features/techdocs/using-cloud-storage,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up TechDocs on major cloud services +Configuring CI/CD to generate and publish TechDocs sites,https://backstage.io/docs/features/techdocs/configuring-ci-cd,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to automate TechDocs publication in CI/CD +TechDocs CLI,https://backstage.io/docs/features/techdocs/cli,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Reference and how-to information on using the CLI. A bit of a catch-all; should be parceled out in more focused docs. +How-To guides,https://backstage.io/docs/features/techdocs/how-to-guides,task,administrator; user,"deployment, use",Recipe,How-tos for various TechDocs tasks. probably partly redundant with other pages. +Troubleshooting,https://backstage.io/docs/features/techdocs/troubleshooting,task,administrator; user,"deployment, use",Maintenance Guide; User Guide,How to solve several trouble scenarios +FAQ,https://backstage.io/docs/features/techdocs/faqs,concept,administrator; user,"deployment, use",KB,Info about the TechDocs plugin. Probably partly redundant with other pages. +Integrations,,,,,, +Overview,https://backstage.io/docs/integrations/,concept,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Intro to integrations. Needs to be expanded. There are about a dozen listed integrations with common cloud providers and software repos. This could be its own supplement to the installation guide or a chapter or appendix. It's almost certain to be needed for any major installation. +Plugins,,,,,, +Intro to plugins,https://backstage.io/docs/plugins/,concept,administrator,deployment,Architecture Overview,"This introduction needs to be expanded (though that material might exist elsewhere). There are pointers here mostly to contributor actions. ""Contributing a plugin"" needs to be its own separate document on the GitHub site." +Existing plugins,https://backstage.io/docs/plugins/existing-plugins,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",This is a pointer to the plugin catalog. The catalog should be an appendix to the installation and config guide. +Create a Backstage Plugin,https://backstage.io/docs/plugins/create-a-plugin,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",This is actually a brief description of how to install a plugin on an existing Backstage instance. +Plugin Development,https://backstage.io/docs/plugins/plugin-development,concept,"contributor, admin","contribute, maintenance",Contributor reference,A brief outline of how to develop a plugin. Should go in the contributor guide. +Structure of a Plugin,https://backstage.io/docs/plugins/structure-of-a-plugin,reference,"contributor, admin","contribute, maintenance",Contributor reference,Description of the structure of a plugin. +Integrate into the Software Catalog,https://backstage.io/docs/plugins/integrating-plugin-into-software-catalog,task,contributor,contribute,Contributor reference,"Describes how to add a plugin to the entities page on a Backstage instance. Described as ""advanced"" and ""experimental""." +Integrating Search into a plugin,https://backstage.io/docs/plugins/integrating-search-into-plugins,task,contributor,contribute,Contributor reference,Instructions for implementing search in a plugin. +Composability System,https://backstage.io/docs/plugins/composability,concept,contributor,contribute,Contributor reference,How plugins talk to each other using React extension. Contains some instructional code that should be separated into a procedure. +Customization (Experimental),https://backstage.io/docs/plugins/customization,task,"contributor, user","contribute, use","Contributor reference, User guide","How to customize a plugin. Instructions for both contributor (plugin developer) and a short snippet for a developer to use in an existing installation. Labeled ""experimental""." +Plugin Analytics,https://backstage.io/docs/plugins/analytics,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","Conceptual, reference, and (mostly) task information about using a supplied analytics API to collect usage data on Backstage." +Feature Flags,https://backstage.io/docs/plugins/feature-flags,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide","How to set features flags to define plugin behavior, both in plugin code and from the Backstage application." +Proxying,https://backstage.io/docs/plugins/proxying,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up an HTTP proxy to reach backend services from the Backstage frontend +Backend plugins,https://backstage.io/docs/plugins/backend-plugin,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Instructions for an admin to create and configure a backend plugin. This is one of those pieces of content that spans admin and contributor. +Call Existing API,https://backstage.io/docs/plugins/call-existing-api,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide",How to call an arbitrary API from the Backstage frontend +URL Reader,https://backstage.io/docs/plugins/url-reader,task,contributor,contribute,Contributor reference,How to use the Backstage URL reader API to securely read files from a plugin. +Testing with Jest,https://backstage.io/docs/plugins/testing,concept,contributor,contribute,Contributor reference,A description of the infrastructure (Jest) and principles to use when writing unit tests for plugins. +Publish private,https://backstage.io/docs/plugins/publish-private,,,,,"""TODO""" +Add to Marketplace,https://backstage.io/docs/plugins/add-to-marketplace,task,contributor,contribute,Contributor reference,How to add a plugin to the plugin library listed in the documentation +Observability,https://backstage.io/docs/plugins/observability,reference,contributor,contribute,Contributor reference,A brief overview of some logging mechanisms. Covered elsewhere. +Configuration,,,,,, +Static Configuration in Backstage,https://backstage.io/docs/conf/,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. +Reading Backstage Configuration,https://backstage.io/docs/conf/reading,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. +Writing Backstage Configuration Files,https://backstage.io/docs/conf/writing,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. +Defining Configuration for your Plugin,https://backstage.io/docs/conf/defining,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. +Auth and identity,,,,,, +Authentication in Backstage,https://backstage.io/docs/auth/,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","How to configure authentication. There are at least 14 individual pages for various providers giving detailed instructions for these providers: ""https://backstage.io/docs/auth/atlassian/provider"" and so on." +Sign-in Identities and Resolvers,https://backstage.io/docs/auth/identity-resolver,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up identities for authorization. Probably useful to plugin contributors as well. +OAuth and OpenID Connect,https://backstage.io/docs/auth/oauth,concept,"contributor, admin","contribute, maintenance","Contributor reference, User guide",Describes how tokens are used by Backstage for third-party services. Includes a sequence diagram. +OIDC provider from scratch,https://backstage.io/docs/auth/oidc,task,"contributor, admin",contribute,Contributor reference,How to use Open ID Connect (OIDC) to connect to Backstage. +Contributing New Providers,https://backstage.io/docs/auth/add-auth-provider,task,contributor,contribute,Contributor reference,How to add support for a new authentication provider. Recommended solely for contributors. +Service to Service Auth,https://backstage.io/docs/auth/service-to-service-auth,task,contributor,contribute,Contributor reference,How to set up a plugin to authenticate another service or plugin. +Troubleshooting Auth,https://backstage.io/docs/auth/troubleshooting,task,"contributor, admin",contribute,"Installation, Setup, and Config Guide",Troubleshooting various authentication problems. These span development of plugins to administration of Backstage instances. +Glossary,https://backstage.io/docs/auth/glossary,reference,all,any,,A glossary of terms for authentication. +Permissions,,,,,, +Overview,https://backstage.io/docs/permissions/overview,concept,all,deployment,Architecture Overview,"An introduction to authorization in Backstage, with a flow diagram." +Concepts,https://backstage.io/docs/permissions/concepts,reference,"contributor, admin","contribute, maintenance",Contributor reference,A glossary of authorization terms. +Getting Started,https://backstage.io/docs/permissions/getting-started,task,"contributor, admin","contribute, maintenance",Contributor reference,How to set up authorization in a Backstage plugin. +Writing a permission policy,https://backstage.io/docs/permissions/writing-a-policy,task,"contributor, admin","contribute, maintenance",Contributor reference,How to write a permission policy in a Typescript file. +Frontend Integration,https://backstage.io/docs/permissions/frontend-integration,task,"contributor, admin","contribute, maintenance",Contributor reference,An example showing what to do when frontend permission policy needs to be set. +Defining custom permission rules,https://backstage.io/docs/permissions/custom-rules,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up a custom rule outside the context of a plugin. +1. Tutorial setup,https://backstage.io/docs/permissions/plugin-authors/01-setup,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. +2. Adding a basic permission check,https://backstage.io/docs/permissions/plugin-authors/02-adding-a-basic-permission-check,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. +3. Adding a resource permission check,https://backstage.io/docs/permissions/plugin-authors/03-adding-a-resource-permission-check,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. +4. Authorizing access to paginated data,https://backstage.io/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. +5. Frontend Components with Authorization,https://backstage.io/docs/permissions/plugin-authors/05-frontend-authorization,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. +Deployment,,,,,, +Overview,https://backstage.io/docs/deployment/,concept,administrator,deployment,"Installation, Setup, and Config Guide",Introduction to deploying a Backstage instance. +Scaling,https://backstage.io/docs/deployment/scaling,concept,administrator,deployment,"Installation, Setup, and Config Guide",Brief discussion of how to scale Backstage across an org +Docker,https://backstage.io/docs/deployment/docker,task,administrator,deployment,"Installation, Setup, and Config Guide",How to deploy using Docker. +Kubernetes,https://backstage.io/docs/deployment/k8s,task,administrator,deployment,"Installation, Setup, and Config Guide",Fairly extensive instructions on how to deploy Backstage using Docker on Kubernetes +Heroku,https://backstage.io/docs/deployment/heroku,task,administrator,deployment,"Installation, Setup, and Config Guide",Deploying using Heroic +Koyeb,https://backstage.io/docs/deployment/koyeb,task,administrator,deployment,"Installation, Setup, and Config Guide",Deploying using Kobe +AWS Fargate via Flightcontrol,https://backstage.io/docs/deployment/flightcontrol,task,administrator,deployment,"Installation, Setup, and Config Guide",Deploying on AWS using Flightcontrol +Designing for Backstage,,,,,, +Design,https://backstage.io/docs/dls/design,concept,contributor,contribute,Contributor overview,Introduction to the Backstage OSS project. +Component Design Guidelines,https://backstage.io/docs/dls/component-design-guidelines,concept,contributor,contribute,Contributor reference,Visual design guidelines for components +Contributing to Storybook,https://backstage.io/docs/dls/contributing-to-storybook,task,contributor,contribute,Contributor reference,How to add a control to the Backstage Storybook catalog +Figma,https://backstage.io/docs/dls/figma,reference,contributor,contribute,Contributor reference,Link to the Figma component library for Backstage +API Reference,,,,,, +Utility APIs,https://backstage.io/docs/api/utility-apis,task,contributor,contribute,Contributor reference,Describes the infrastructure for creating and using APIs that operate between plugins. +Package Index,https://backstage.io/docs/reference/,reference,contributor,contribute,Contributor reference,A lengthy catalog of APIs +Deprecations,https://backstage.io/docs/api/deprecations,reference,all,any,,Describes deprecated elements in Backstage. Deprecations should be noted in reference material and described in release notes. +Tutorials,,,,,, +Future developer journey,https://backstage.io/docs/tutorials/journey,task,"contributor, admin",contribute,Recipe,"Extended example about a fictional developer adding a new plugin to an installation, then to the project" +Adding Custom Plugin to Existing Monorepo App,https://backstage.io/docs/tutorials/quickstart-app-plugin,task,administrator,deployment,Recipe,How to develop a plugin in an existing Backstage installation (app) +React Router 6.0 Migration,https://backstage.io/docs/tutorials/react-router-stable-migration,task,administrator,"installation, setup, config",Release Notes,"How to upgrade to a newer version of React router. A version-specific procedure that should be hidden from general admin procedures. Should have been a release-specific task, if necessary at all" +Package Role Migration,https://backstage.io/docs/tutorials/package-role-migration,task,administrator,"installation, setup, config",Release Notes,"Another transitional step that should be part of a version upgrade, not a user tutorial." +Migrating away from @backstage/core,https://backstage.io/docs/tutorials/migrating-away-from-core,task,administrator,"installation, setup, config",Release Notes,Another refactoring migration. Remove from tutorials. +Configuring Plugin Databases,https://backstage.io/docs/tutorials/configuring-plugin-databases,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","I could see putting this in a recipe guide or a config guide, plugin-specific or otherwise. Not a tutorial." +Switching Backstage from SQLite to PostgreSQL,https://backstage.io/docs/tutorials/switching-sqlite-postgres,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to change the default DB from SQLite to PostgreSQL. This should be in the basic configuration guide. +Using the Backstage Proxy from Within a Plugin,https://backstage.io/docs/tutorials/using-backstage-proxy-within-plugin,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to access an external API using a proxy. A plugin configuration task. +Migration to Yarn 3,https://backstage.io/docs/tutorials/yarn-migration,task,administrator,deployment,Release Notes,Another release-specific migration. Remove from tutorials. +Architecture Decision Records (ADRs),,,,,, +Overview,https://backstage.io/docs/architecture-decisions/,concept,"contributor, admin",deployment,Architecture Overview,"An intro to architectural decision records (ADRs). Potentially part of an architecture overview. Could be omitted from the user doc altogether, though. Primarily of interest to contributors." +ADR001: Architecture Decision Record (ADR) log,https://backstage.io/docs/architecture-decisions/adrs-adr001,concept,contributor,contribute,Contributor reference,Meta ADR about where to store ADRs. +ADR002: Default Software Catalog File Format,https://backstage.io/docs/architecture-decisions/adrs-adr002,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR003: Avoid Default Exports and Prefer Named Exports,https://backstage.io/docs/architecture-decisions/adrs-adr003,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR004: Module Export Structure,https://backstage.io/docs/architecture-decisions/adrs-adr004,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR005: Catalog Core Entities,https://backstage.io/docs/architecture-decisions/adrs-adr005,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR006: Avoid React.FC and React.SFC,https://backstage.io/docs/architecture-decisions/adrs-adr006,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR007: Use MSW to mock http requests,https://backstage.io/docs/architecture-decisions/adrs-adr007,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR008: Default Catalog File Name,https://backstage.io/docs/architecture-decisions/adrs-adr008,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR009: Entity References,https://backstage.io/docs/architecture-decisions/adrs-adr009,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR010: Use the Luxon Date Library,https://backstage.io/docs/architecture-decisions/adrs-adr010,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR011: Plugin Package Structure,https://backstage.io/docs/architecture-decisions/adrs-adr011,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR012: Use Luxon.toLocaleString and date/time presets,https://backstage.io/docs/architecture-decisions/adrs-adr012,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR013: Proper use of HTTP fetching libraries,https://backstage.io/docs/architecture-decisions/adrs-adr013,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +FAQ,,,,,, +FAQ,https://backstage.io/docs/FAQ,reference,all,any,KB,"This is a fairly robust FAQ. I usually recommend doing away with a FAQ on the grounds that it's a last resort for someone looking for information. Distribute its topics to where they belong in the documentation. Use a knowledge base (similar, but longer-format articles with conceptual information only) for miscellaneous, indexed, conceptual information." +Experimental Backend System,,,,,, +Introduction,https://backstage.io/docs/backend-system/,concept,"contributor, admin",deployment,Contributor reference,"Information about a refactoring of existing functionality should be kept in the developer (contributor) discussion until it is deployed, at which point it should be documented in the release notes. Mentions of timing (""this component is in alpha""; ""currently this works like this""; ""we plan to ..."") should be avoided entirely in the product regular documentation. Version-specific information should be documented at the time of release in the release notes. If the change affects functionality, the new functionality should replace the old in the documentation set starting at the new version of the doc." +Overview,https://backstage.io/docs/backend-system/architecture/index,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" +Services,https://backstage.io/docs/backend-system/architecture/services,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" +Plugins,https://backstage.io/docs/backend-system/architecture/plugins,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" +Extension Points,https://backstage.io/docs/backend-system/architecture/extension-points,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" +Modules,https://backstage.io/docs/backend-system/architecture/modules,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" +Naming Patterns,https://backstage.io/docs/backend-system/architecture/naming-patterns,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" +Accessibility,,,,,, +Backstage Accessibility,https://backstage.io/docs/accessibility/,task,contributor,contribute,Contributor reference,How to incorporate accessibility into contributed software components diff --git a/assessments/0008-backstage/backstage-glossary.md b/analysis/0008-backstage/backstage-glossary.md similarity index 100% rename from assessments/0008-backstage/backstage-glossary.md rename to analysis/0008-backstage/backstage-glossary.md diff --git a/assessments/0008-backstage/backstage-implementation.md b/analysis/0008-backstage/backstage-implementation.md similarity index 100% rename from assessments/0008-backstage/backstage-implementation.md rename to analysis/0008-backstage/backstage-implementation.md diff --git a/assessments/0008-backstage/backstage-insights-summary.md b/analysis/0008-backstage/backstage-insights-summary.md similarity index 100% rename from assessments/0008-backstage/backstage-insights-summary.md rename to analysis/0008-backstage/backstage-insights-summary.md diff --git a/assessments/0008-backstage/backstage-issues.md b/analysis/0008-backstage/backstage-issues.md similarity index 100% rename from assessments/0008-backstage/backstage-issues.md rename to analysis/0008-backstage/backstage-issues.md diff --git a/assessments/0008-backstage/user-roles.md b/analysis/0008-backstage/user-roles.md similarity index 100% rename from assessments/0008-backstage/user-roles.md rename to analysis/0008-backstage/user-roles.md diff --git a/assessments/0009-in-toto/README.md b/analysis/0009-in-toto/README.md similarity index 100% rename from assessments/0009-in-toto/README.md rename to analysis/0009-in-toto/README.md diff --git a/assessments/0009-in-toto/in-toto-analysis.md b/analysis/0009-in-toto/in-toto-analysis.md similarity index 100% rename from assessments/0009-in-toto/in-toto-analysis.md rename to analysis/0009-in-toto/in-toto-analysis.md diff --git a/assessments/0009-in-toto/in-toto-doc-issues.md b/analysis/0009-in-toto/in-toto-doc-issues.md similarity index 100% rename from assessments/0009-in-toto/in-toto-doc-issues.md rename to analysis/0009-in-toto/in-toto-doc-issues.md diff --git a/assessments/0009-in-toto/in-toto-implementation.md b/analysis/0009-in-toto/in-toto-implementation.md similarity index 100% rename from assessments/0009-in-toto/in-toto-implementation.md rename to analysis/0009-in-toto/in-toto-implementation.md diff --git a/assessments/0009-in-toto/survey-of-existing-doc.md b/analysis/0009-in-toto/survey-of-existing-doc.md similarity index 100% rename from assessments/0009-in-toto/survey-of-existing-doc.md rename to analysis/0009-in-toto/survey-of-existing-doc.md diff --git a/assessments/0010-etcd/README.md b/analysis/0010-etcd/README.md similarity index 100% rename from assessments/0010-etcd/README.md rename to analysis/0010-etcd/README.md diff --git a/assessments/0010-etcd/etcd-analysis.md b/analysis/0010-etcd/etcd-analysis.md similarity index 100% rename from assessments/0010-etcd/etcd-analysis.md rename to analysis/0010-etcd/etcd-analysis.md diff --git a/assessments/0010-etcd/etcd-implementation.md b/analysis/0010-etcd/etcd-implementation.md similarity index 100% rename from assessments/0010-etcd/etcd-implementation.md rename to analysis/0010-etcd/etcd-implementation.md diff --git a/assessments/0010-etcd/etcd-issues.md b/analysis/0010-etcd/etcd-issues.md similarity index 100% rename from assessments/0010-etcd/etcd-issues.md rename to analysis/0010-etcd/etcd-issues.md diff --git a/assessments/0011-keda/README.md b/analysis/0011-keda/README.md similarity index 100% rename from assessments/0011-keda/README.md rename to analysis/0011-keda/README.md diff --git a/assessments/0011-keda/keda-analysis.md b/analysis/0011-keda/keda-analysis.md similarity index 100% rename from assessments/0011-keda/keda-analysis.md rename to analysis/0011-keda/keda-analysis.md diff --git a/assessments/0011-keda/keda-implementation.md b/analysis/0011-keda/keda-implementation.md similarity index 100% rename from assessments/0011-keda/keda-implementation.md rename to analysis/0011-keda/keda-implementation.md diff --git a/assessments/0011-keda/keda-issues.md b/analysis/0011-keda/keda-issues.md similarity index 100% rename from assessments/0011-keda/keda-issues.md rename to analysis/0011-keda/keda-issues.md diff --git a/analysis/README.md b/analysis/README.md new file mode 100644 index 0000000..ca3dff5 --- /dev/null +++ b/analysis/README.md @@ -0,0 +1,48 @@ +# CNCF TechDocs Analysis for OSS Projects + +This directory contains: + +- Analyses of the technical documentation for selected CNCF incubating and graduated software projects. +- Tools (templates, analysis criteria, background information) to enable a mid- to senior-level technical writer to perform an analysis independently with some support from the CNCF tech docs staff. + +## Project Analyses + +There are two rounds of projects: + +1. Analyses **0001** - **0007** are a first round of projects completed as "assessments" through the CNCF Help Desk. The file `000N-projectname.md` file is the sole artifact of the assessment in each case. The last one was added in May 2023. +2. Subsequent analyses were commissioned starting in November 2023. Each has its own directory, `00NN-projectname`, containing three analysis artifacts: + - `projectname-analysis.md` evaluates the project documentation and provides comments and recommendations in a manner very similar to the first round of tech doc assessments. This document is based on the analysis template and accompanying criteria developed for the first round. + - `projectname-implementation.md` provides concrete actions that can be implemented by project contributors. Its focus is on specific, achievable work that will have a strong positive impact on document effectiveness. + - `projectname-issues.md` is a backlog of improvement actions, meant to be entered as GitHub Issues, derived from `projectname-implementation.md`. + +## Analyst Tools + +Read and follow the guidelines in the `analyst-tools` directory to perform a documentation analysis for CNCF. These guidelines provide: +- A relatively objective set of criteria (a "rubric") for evaluating technical documentation. +- An attempt the documentation analysis to the current (or proposed) maturity level for the overall project. +- A consistent set of criteria on which to evaluate existing documentation and website content, infrastructure, and support. +- Emphasis on effective documentation that serves all users associated with the project. + +### How-to + +This document contains a general discussion of the CNCF Tech Docs analysis program and instructions for requesting, writing, and consuming an analysis. + +### Criteria + +This document describes the criteria used to evaluate a project's technical documentation and website. These criteria are also referred to as a "rubric" elsewhere in this repo. + +### Templates + +These are templates for the analysis artifacts. + +#### Analysis Template + +This is the main analysis template, based on the work of the original 2021-23 tech docs assessments. + +#### Implementation Plan + +The implementation plan is an intermediate step between the analysis and the issues backlog, meant as an aid to digesting the analysis recommendations into actionable issues. + +#### Issues + +This is the final backlog of recommended changes to the documentation, meant to be transferred more or less directly into the GitHub Issues of the project documentation repo. \ No newline at end of file diff --git a/analysis/analysis-tools/New CNCF tech doc artifacts.md b/analysis/analysis-tools/New CNCF tech doc artifacts.md new file mode 100644 index 0000000..90e27e2 --- /dev/null +++ b/analysis/analysis-tools/New CNCF tech doc artifacts.md @@ -0,0 +1,54 @@ +# New CNCF tech doc artifacts + +## Existing + +How-to +Template +Criteria + +1. Revise template to match what I've done +2. Explain how to build out the umbrella and sub-issues +3. Create another folder for the process + +## Artifacts: +README: preamble, theory, objectives, audience, lay out the program. Then link to: + +How-to: checklist or recipe. CNCF requirements -- what does Nate need? + +Template: update. + +Criteria: how do you evaluate? + +Scoring/ranking - purposes: +- Appearance of objectivity +- Maturity level of software +- Shame maintainers into taking doc seriously +- Expected + +Scoring: needed or not? + +| Reason | Importance | Notes | +| --- | --- | --- | +| Objectivity | | Gives at least the appearance of an objective evaluation (that's why I started using the term "rubric", btw) | +| Objectivity, appearance of | | Gives at least the appearance of an objective evaluation (that's why I started using the term "rubric", btw) | +| Shame maintainers | | | +| Match software maturity | | Agree that for incubating and graduated projects | +| Expected | | Quantitative analysis vs. Qualitative? | +| | | | + +Evaluate on effort vs impact? + +Documentation for Developers + +## Audiences: +1. Maintainers - what's in it for me? +2. Analyst - doing the analysis work - what is "done"? +3. Foundation (CNCF) - keep the customer satisfied - should address expectation. +4. Foundation (other) - want to be able to use as a model for other orgs. +5. Contributors - writers who pick up the work -- need to define what we expect of these people. + +## Repo Outline + +- **cncf-techdocs** + - **docs**: Documentation + - \ No newline at end of file diff --git a/assessments/criteria.md b/analysis/analysis-tools/criteria.md similarity index 100% rename from assessments/criteria.md rename to analysis/analysis-tools/criteria.md diff --git a/assessments/howto.md b/analysis/analysis-tools/howto.md similarity index 100% rename from assessments/howto.md rename to analysis/analysis-tools/howto.md diff --git a/assessments/template.md b/analysis/analysis-tools/template.md similarity index 100% rename from assessments/template.md rename to analysis/analysis-tools/template.md diff --git a/docs/README.md b/resources/README.md similarity index 100% rename from docs/README.md rename to resources/README.md diff --git a/docs/analytics.md b/resources/analytics.md similarity index 100% rename from docs/analytics.md rename to resources/analytics.md diff --git a/docs/hugo-and-docsy.md b/resources/hugo-and-docsy.md similarity index 100% rename from docs/hugo-and-docsy.md rename to resources/hugo-and-docsy.md diff --git a/docs/images/folder-based-etcd.png b/resources/images/folder-based-etcd.png similarity index 100% rename from docs/images/folder-based-etcd.png rename to resources/images/folder-based-etcd.png diff --git a/docs/images/subdomain-based-k8s.png b/resources/images/subdomain-based-k8s.png similarity index 100% rename from docs/images/subdomain-based-k8s.png rename to resources/images/subdomain-based-k8s.png diff --git a/docs/localization/README.md b/resources/localization/README.md similarity index 100% rename from docs/localization/README.md rename to resources/localization/README.md diff --git a/docs/netlify-domains-setup.md b/resources/netlify-domains-setup.md similarity index 100% rename from docs/netlify-domains-setup.md rename to resources/netlify-domains-setup.md diff --git a/docs/repo-setup.md b/resources/repo-setup.md similarity index 100% rename from docs/repo-setup.md rename to resources/repo-setup.md diff --git a/docs/searching-documentation.md b/resources/searching-documentation.md similarity index 100% rename from docs/searching-documentation.md rename to resources/searching-documentation.md diff --git a/docs/services.md b/resources/services.md similarity index 100% rename from docs/services.md rename to resources/services.md diff --git a/docs/versioning-documentation.md b/resources/versioning-documentation.md similarity index 100% rename from docs/versioning-documentation.md rename to resources/versioning-documentation.md diff --git a/docs/website-guidelines-checklist.md b/resources/website-guidelines-checklist.md similarity index 100% rename from docs/website-guidelines-checklist.md rename to resources/website-guidelines-checklist.md From af91f2f50d08e337d83ab8afd7dbf3d2998621ab Mon Sep 17 00:00:00 2001 From: David Welsch Date: Mon, 29 Apr 2024 15:42:42 -0700 Subject: [PATCH 02/10] Updated. Signed-off-by: David Welsch Signed-off-by: Patrice Chalin --- README.md | 2 +- TechDoc-Assistance-Program.md | 43 +++++++++++++++-------------------- 2 files changed, 19 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 28634b3..57e1c37 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ We store ongoing meeting notes in a [Google doc](https://docs.google.com/documen ## The Technical Documentation Assistance Program -The CNCF Tech Doc team has created a program to assist CNCF-affiliated projects in creating effective documentation. [`TechDoc-Assistance-Program.md`](./TechDoc%20Assistance%20Program%20Outline.md) contains an outline of this program. +The CNCF Tech Doc team has created a program to assist CNCF-affiliated projects in creating effective documentation. [`TechDoc-Assistance-Program.md`](./TechDoc-Assistance-Program.md) contains an outline of this program. Project maintainers are asked to understand that: - Project documentation resources are *always* underestimated. diff --git a/TechDoc-Assistance-Program.md b/TechDoc-Assistance-Program.md index 785664c..04754ee 100644 --- a/TechDoc-Assistance-Program.md +++ b/TechDoc-Assistance-Program.md @@ -2,15 +2,13 @@ This document outlines the Cloud Native Computing Foundation (CNCF) Technical Documentation Assistance Program (the Program), a service offered by CNCF Tech Docs for evaluating and improving an OSS project's technical documentation. The process is designed to: -1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level]. (Often, documentation help is requested when a project requests promotion to a new maturity level.) +1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level](analysis/analysis-tools/criteria.md. (Often, documentation help is requested when a project requests promotion to a new maturity level.) 1. Recommend changes that will reduce the gap between the documentation and the maturity of the overall project. 1. Expand on the recommended changes in an implementation plan. -1. Break down the implementation into a documentation project backlog comprising an Issues (in GitHub) list. +1. Break down the implementation into a documentation project backlog comprising a GitHub Issues list. 1. Support the project team's contributors in taking up and completing the issue backlog items. 1. Leave the project team with an improved understanding and skill base for improving and maintaining the project documentation. -This outline is a working document that presents current aspirations for the Program. It describes both existing elements of the Program and elements that are under discussion. All elements described are existing unless indicated by **TBD**. - ## Phase 0: Training Some level of familiarity with the technical documentation process is required to: @@ -23,40 +21,35 @@ For this reason, CNCF offers free training on documentation essentials for proje The training program consists of the following online courses. Anyone can sign up for and complete the courses at their own pace. -1. Open Source Doc Essentials LFC111 -1. +1. [Open Source Technical Documentation Essentials (LFC111)](https://training.linuxfoundation.org/training/open-source-technical-documentation-essentials-lfc111/) +1. [Creating Effective Documentation for Developers (LFC112)](https://training.linuxfoundation.org/training/creating-effective-documentation-for-developers-lfc112/) ## Phase 1: Documentation Analysis A technical writer (on CNCF staff or on contract) analyzes the documentation. Based on the standards developed by the CNCF Tech Docs program, the writer: 1. Estimates the maturity level of the documentation compared to the current or desired maturity level of the software project, based on a number of criteria in three categories, using a rubric developed by CNCF. The categories are: - 1. Project documentation: The end-user documentation for the project's work product, typically (but not always) an application, API, protocol, or some other software product. - 1. Contributor documentation: Documentation about the project, aimed at project contributors and describing procedures, infrastructure, and customs for doing project work. This includes artifacts that define procedures and governance; recruit, orient, and train project contributors; and name responsible parties (project leaders, often generically called *maintainers*). - 1. Website: The technical infrastructure behind the documentation and the project's web presence, including website generation, versioning, SEO, analytics, and security. -1. Collaborates with project leadership to identify user roles and objectives for software users. If leadership + 1. Project documentation: The end-user documentation for the project's work product, typically (but not always) an application, API, protocol, or some other software product. + 1. Contributor documentation: Documentation about the project, aimed at project contributors and describing procedures, infrastructure, and customs for doing project work. This includes artifacts that define procedures and governance; recruit, orient, and train project contributors; and name responsible parties (project leaders, often generically called *maintainers*). + 1. Website: The technical infrastructure behind the documentation and the project's web presence, including website generation, versioning, SEO, analytics, and security. +1. Collaborates with project leadership to identify user roles and objectives for software users. 1. Proposes changes, if necessary, to the organization and content of the documentation to close gaps with the proposed maturity level. +1. Writes an implementation plan describing improvements that address the gaps identified in the analysis. -## Phase 2: Issues - -Once a high-level improvement plan has been written and approved, the tech writer: - -1. Analyzes the proposed changes to create a roadmap to move the project toward the proposed level. -2. Creates issues for specific writing assignments and other tasks to improve the documentation. +## Phase 2: Backlog Creation -The issues are graded on two axes: +Once a high-level improvement plan has been written and approved, the tech writer analyzes the proposed changes to create a backlog of actionable, individual writing assignments and other tasks to improve the documentation. These tasks should have two primary characteristics: +- As much as possible, they should be independent of each other so they can be completed in any order by any combination of contributors; and +- They should be time-constrained. If possible, large tasks should be broken down into smaller, independent tasks that require hours, not days, to complete. -- Impact: How important the issue is to 1) improving the doc effectiveness and 2) moving the doc toward the desired maturity level. -- Effort: Amount of work the issue is estimated to require to complete. This includes primarily the work of writers and editors, but also SME discussion, review, and approval. +## Phase 3: Documentation Improvement -Of course, it's recommended that the project prioritize higher impact and lower effort issues first. +Community members work on the issues created in the previous phase. Ideally, tech writers are available to advise contributors and edit work, especially if the contributing community members are not trained technical writers. Remember that the training courses in Phase 0 are available to prepare contributors with general knowledge of the process. -## Phase 3: Implementation - -Community members work on the issues created in the previous phase. Ideally, tech writers are available to advise contributors and edit work, especially if the contributing community members are not trained technical writers. +We know that recruiting contributors to write documentation can be difficult. While this is largely the responsibility of the project leadership, CNCF is actively working on ways to encourage doc contributions. For example, creating a backlog of time-bounded issues is an attempt to lower barriers, both psychological and logistical, to documentation creation and maintenance. ## Phase 4: Impact Analysis -To gauge the effectiveness of the documentation effort, we recommend that the project track the documentation issues. Projects are encouraged to collect further metrics on documentation effectiveness. At a minimum though, tracking the issues should provide a guide to progress on leveling the documentation maturity to that of the project. - +Measurement is vital to any process improvement effort, and this is currently the weakest point of the TechDoc Assistance Program. We do no offer any tools to measure the impact of doc improvements, although we can assure you that they are profound. Projects are encouraged to collect metrics on documentation effectiveness. +As a basic gauge the effectiveness of the documentation effort, projects can track the issue backlog. This can provide a guide to progress on leveling the documentation maturity to that of the project. From f042ad820fb5c55b6161dcdbf64bb780cc8dd771 Mon Sep 17 00:00:00 2001 From: David Welsch Date: Fri, 3 May 2024 15:59:28 -0700 Subject: [PATCH 03/10] Completed first draft of tech doc analysis READMEs, instructions, and templates. Reorganized tech-docs directory structure. Signed-off-by: David Welsch Signed-off-by: Patrice Chalin --- analysis/README.md | 75 ++- .../New CNCF tech doc artifacts.md | 54 -- analysis/analysis-tools/analysis-template.md | 476 ++++++++++++++++++ analysis/analysis-tools/criteria.md | 14 +- analysis/analysis-tools/howto.md | 120 +++-- .../analysis-tools/implementation-template.md | 35 ++ analysis/analysis-tools/issue-template.md | 40 ++ analysis/analysis-tools/template.md | 112 ----- .../analysis-tools/umbrella-issue-template.md | 31 ++ 9 files changed, 728 insertions(+), 229 deletions(-) delete mode 100644 analysis/analysis-tools/New CNCF tech doc artifacts.md create mode 100644 analysis/analysis-tools/analysis-template.md create mode 100644 analysis/analysis-tools/implementation-template.md create mode 100644 analysis/analysis-tools/issue-template.md delete mode 100644 analysis/analysis-tools/template.md create mode 100644 analysis/analysis-tools/umbrella-issue-template.md diff --git a/analysis/README.md b/analysis/README.md index ca3dff5..dc2f65c 100644 --- a/analysis/README.md +++ b/analysis/README.md @@ -1,48 +1,71 @@ # CNCF TechDocs Analysis for OSS Projects -This directory contains: +## Purpose -- Analyses of the technical documentation for selected CNCF incubating and graduated software projects. -- Tools (templates, analysis criteria, background information) to enable a mid- to senior-level technical writer to perform an analysis independently with some support from the CNCF tech docs staff. +The goals of a CNCF technical documentation analysis are to: -## Project Analyses +- Examine the current project technical documentation and website against the CNCF's analysis framework, as described in the doc analysis [criteria](./criteria.md). +- Compare the documentation against the current or proposed maturity level for the overall project. +- Recommends a program of key improvements with the largest return on investment. These improvements are documented as *recommendations* in the analysis document and expanded in a companion [implementation plan](./implementation-template.md) and [issues backlog](./umbrella-issue-template.md). -There are two rounds of projects: +## Contents -1. Analyses **0001** - **0007** are a first round of projects completed as "assessments" through the CNCF Help Desk. The file `000N-projectname.md` file is the sole artifact of the assessment in each case. The last one was added in May 2023. -2. Subsequent analyses were commissioned starting in November 2023. Each has its own directory, `00NN-projectname`, containing three analysis artifacts: - - `projectname-analysis.md` evaluates the project documentation and provides comments and recommendations in a manner very similar to the first round of tech doc assessments. This document is based on the analysis template and accompanying criteria developed for the first round. +In this directory: + +- **Project Analyses**: `analysis` contains analyses of the technical documentation for selected CNCF incubating and graduated software projects. +- **Analysis Tools**: `analysis-tools` contains instructions, templates, analysis criteria, and background information to enable a mid- to senior-level technical writer to perform an analysis independently with some support from the CNCF tech docs staff. + +### Project Analyses + +Completed analyses are contained in the `analysis` directory. + +There are two rounds of projects, *Round 1* and *Round 2*. + +#### Round 1 + +Analyses **0001** - **0007** are a first round of projects completed as "assessments" through the CNCF Help Desk. The `000N-projectname.md` file is the sole artifact of the assessment in each case. The last one was added in May 2023. + +#### Round 2 + +Subsequent analyses were commissioned starting in November 2023. Each has its own directory, `00NN-projectname`, containing three analysis artifacts: + - `projectname-analysis.md` evaluates the project documentation and provides comments and recommendations in a manner very similar to the Round 1 tech doc assessments. This document is based on the analysis template and accompanying criteria developed for the Round 1. - `projectname-implementation.md` provides concrete actions that can be implemented by project contributors. Its focus is on specific, achievable work that will have a strong positive impact on document effectiveness. - `projectname-issues.md` is a backlog of improvement actions, meant to be entered as GitHub Issues, derived from `projectname-implementation.md`. -## Analyst Tools +### Analysis Tools -Read and follow the guidelines in the `analyst-tools` directory to perform a documentation analysis for CNCF. These guidelines provide: -- A relatively objective set of criteria (a "rubric") for evaluating technical documentation. -- An attempt the documentation analysis to the current (or proposed) maturity level for the overall project. -- A consistent set of criteria on which to evaluate existing documentation and website content, infrastructure, and support. -- Emphasis on effective documentation that serves all users associated with the project. +Templates and instructions for doing the analyses are contained in the `analysis-tools` directory. -### How-to +#### Audience -This document contains a general discussion of the CNCF Tech Docs analysis program and instructions for requesting, writing, and consuming an analysis. +This directory is for primarily for members of the CNCF TechDocs team, including contractors or consultants, who need to conduct or assist with an analysis of a CNCF open-source project's technical documentation. Readers in other roles can also benefit from understanding the guidelines in this directory: -### Criteria +- **Project maintainers** can learn how improved technical documentation can increase the effectiveness of the project software, speed adoption, and improve user satisfaction. +- **CNCF Foundation members** can learn what benefits can (and cannot) be expected of a documentation improvement effort. +- **Members of other open-source software foundations** can use the analysis tools as a model, in whole or in part, for their own documentation improvement processes. (Please contact the Cloud Native Computing Foundation to discuss licensing and permission.) +- **Project contributors** can learn what factors go into improving technical documentation and what is expected of contributors who work on project documentation issues. -This document describes the criteria used to evaluate a project's technical documentation and website. These criteria are also referred to as a "rubric" elsewhere in this repo. +#### Contents -### Templates +Use the guidelines and templates in this directory to perform a documentation analysis for CNCF. These materials provide: +- A relatively objective set of criteria (a "rubric") for evaluating existing documentation and website content, infrastructure, and support. +- An attempt to make the documentation analysis appropriate to the current (or proposed) maturity level for the overall project. +- Emphasis on effective documentation that serves all users associated with the project. -These are templates for the analysis artifacts. +##### How-to -#### Analysis Template +`howto.md` contains instructions for requesting, writing, and consuming an analysis. -This is the main analysis template, based on the work of the original 2021-23 tech docs assessments. +##### Criteria -#### Implementation Plan +`criteria.md` describes the criteria used to evaluate a project's technical documentation and website. These criteria are also referred to as a "rubric" elsewhere in this repo. The criteria are unchanged between the first and second round of analyses. -The implementation plan is an intermediate step between the analysis and the issues backlog, meant as an aid to digesting the analysis recommendations into actionable issues. +##### Templates -#### Issues +These are templates for the analysis artifacts. -This is the final backlog of recommended changes to the documentation, meant to be transferred more or less directly into the GitHub Issues of the project documentation repo. \ No newline at end of file +- **Analysis Template**: `analysis-template.md` is the main analysis template, based on the work of the original 2021-23 tech docs assessments. +- **Implementation Plan**: The implementation plan, represented in `implementation-template.md`, is an intermediate step between the analysis and the issues backlog, meant as an aid to digesting the analysis recommendations into actionable issues. +- **Issues**: This is the final backlog of recommended changes to the documentation, meant to be transferred directly into the GitHub Issues of the project documentation repo. There are two templates: + - `issue-template.md` is a template for individual issues that can be use to create issues in GitHub. + - `umbrella-issue-template.md` can be used to create an umbrella issue in GitHub, and can also be used as a template for a `_PROJECT_-issues.md` document to be included in the analysis pull request. \ No newline at end of file diff --git a/analysis/analysis-tools/New CNCF tech doc artifacts.md b/analysis/analysis-tools/New CNCF tech doc artifacts.md deleted file mode 100644 index 90e27e2..0000000 --- a/analysis/analysis-tools/New CNCF tech doc artifacts.md +++ /dev/null @@ -1,54 +0,0 @@ -# New CNCF tech doc artifacts - -## Existing - -How-to -Template -Criteria - -1. Revise template to match what I've done -2. Explain how to build out the umbrella and sub-issues -3. Create another folder for the process - -## Artifacts: -README: preamble, theory, objectives, audience, lay out the program. Then link to: - -How-to: checklist or recipe. CNCF requirements -- what does Nate need? - -Template: update. - -Criteria: how do you evaluate? - -Scoring/ranking - purposes: -- Appearance of objectivity -- Maturity level of software -- Shame maintainers into taking doc seriously -- Expected - -Scoring: needed or not? - -| Reason | Importance | Notes | -| --- | --- | --- | -| Objectivity | | Gives at least the appearance of an objective evaluation (that's why I started using the term "rubric", btw) | -| Objectivity, appearance of | | Gives at least the appearance of an objective evaluation (that's why I started using the term "rubric", btw) | -| Shame maintainers | | | -| Match software maturity | | Agree that for incubating and graduated projects | -| Expected | | Quantitative analysis vs. Qualitative? | -| | | | - -Evaluate on effort vs impact? - -Documentation for Developers - -## Audiences: -1. Maintainers - what's in it for me? -2. Analyst - doing the analysis work - what is "done"? -3. Foundation (CNCF) - keep the customer satisfied - should address expectation. -4. Foundation (other) - want to be able to use as a model for other orgs. -5. Contributors - writers who pick up the work -- need to define what we expect of these people. - -## Repo Outline - -- **cncf-techdocs** - - **docs**: Documentation - - \ No newline at end of file diff --git a/analysis/analysis-tools/analysis-template.md b/analysis/analysis-tools/analysis-template.md new file mode 100644 index 0000000..6d2cbd3 --- /dev/null +++ b/analysis/analysis-tools/analysis-template.md @@ -0,0 +1,476 @@ +--- +title: _PROJECT_ Documentation Analysis +tags: _PROJECT_ +created: YYYY-MM-DD +modified: YYYY-MM-DD +author: _NAME_ (@_HANDLE_) +--- + + + +# Introduction + +This document analyzes the effectiveness and completeness of the [_PROJECT_][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. + +According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first step of a CNCF process aimed at assisting projects with their documentation efforts. + +## Purpose + +This document was written to analyze the current state of _PROJECT_ documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second document, `_PROJECT_-impementation.md`, outlines an actionable plan for improvement. A third document, `_PROJECT_-issues.md`, enumerates a backlog of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. + +This document: + +- Analyzes the current _PROJECT_ technical documentation and website +- Compares existing documentation against the CNCF’s standards +- Recommends a program of key improvements with the largest return on investment + +## Scope of analysis + +The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the _PROJECT_ GitHub repository. + +The _PROJECT_ website and documentation are written in [Markdown, ReStructured Text, other] and are compiled using the [Hugo, Docusaurus, Sphynx, other] static site generator with the [Docsy, other] theme and served from [the Netlify platform, other]. The site's code is stored on the _PROJECT_ GitHub repo. + +**In scope:** +- Website: _PROJECT-WEBSITE_ +- Documentation: _PROJECT-DOC-URL_ +- Website repo: _PROJECT-DOC-REPO_ +- _[Other; might include a demo server, governance site, or other relevant repositories]_ + +**Out of scope:** +- Other _PROJECT_ repos: _[In general, do not include sub-projects or related "ecosystem" projects]_ + + +## How this document is organized + +This document is divided into three sections that represent three major areas of concern: + +- **Project documentation:** concerns documentation for users of the _PROJECT_ software, aimed at people who intend to use the project software +- **Contributor documentation:** concerns documentation for new and existing contributors to the _PROJECT_ OSS project +- **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability + +Each section begins with summary ratings based on a rubric with appropriate [criteria][criteria-doc] for the section, then proceeds to: +- **Comments**: observations about the existing documentation, with a focus on how it does or does not help _PROJECT_ users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of the documentation. + +An accompanying document, [`_PROJECT_-implementation.md`][implementation-doc], breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed into a series of [issues][issues-doc] and entered as GitHub [issues][project-doc-website]/issues. + + +## How to use this document + +Readers interested only in actionable improvements should skip this document and read the [implementation plan][implementation-doc] and [issues list][issues-doc]. + +Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: + +- [Project documentation][project-heading] +- [Contributor documentation][contributor-heading] +- [Website and documentation infrastructure][website-heading] + +Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria][criteria-doc] specification. + + +### Recommendations, requirements, and best practices + +This analysis measures documentation against CNCF project maturity standards, and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how to apply documentation best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-spec], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. + + +# Project documentation + + +_PROJECT_ is a **graduated** project of CNCF. This means that the project should have [*very high*][criteria-doc] standards for documentation. + +_PROJECT_ is an **incubating** project of CNCF. This means that the project should be [*developing*][criteria-doc] professional-quality documentation alongside the project code. + +| Criterion | Rating (1-5) | +| --- | --- | +| Information architecture | (rating value) | +| New user content | (rating value) | +| Content maintainability | (rating value) | +| Content creation processes | (rating value) | +| Inclusive language | (rating value) | + + + +## Comments + + + +The following sections contain brief assessments of each element of the Project Documentation rubric. + + + +### Information architecture + +The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: + +* Is there high level conceptual/“About” content? +Is the documentation feature complete? (i.e., each product feature is documented) +* Are there step-by-step instructions (tasks, tutorials) documented for features? +* Are there any key features which are documented but missing task documentation? +* Is the “happy path”/most common use case documented? +Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) +* If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) +* If the product exposes an API, is there a complete reference? +* Is content up to date and accurate? + +### New user content + +New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: + +* Is “getting started” clearly labeled? (“Getting started”, “Installation”, “First steps”, etc.) +* Is installation documented step-by-step? +* If needed, are multiple OSes documented? +* Do users know where to go after reading the getting started guide? +* Is your new user content clearly signposted on your site’s homepage or at the top of your information architecture? +* Is there easily copy-pastable sample code or other example content? + + +### Content maintainability & site mechanics + +As a project scales, concerns like localized (translated) content and versioning become large maintenance burdens, particularly if you don’t plan for them. + +We evaluate on the following: + +* Is your documentation searchable? +* Are you planning for localization/internationalization with regards to site directory structure? Is a localization framework present? +* Do you have a clearly documented method for versioning your content? + + +### Content creation processes + +Documentation is only as useful as it is accurate and well-maintained, and requires the same kind of review and approval processes as code. + +We evaluate on the following: + +* Is there a clearly documented (ongoing) contribution process for documentation? +* Does your code release process account for documentation creation & updates? +* Who reviews and approves documentation pull requests? +* Does the website have a clear owner/maintainer? + + +### Inclusive language + +Creating inclusive project communities is a key goal for all CNCF projects. + +We evaluate on the following: + +* Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website? +* Does the project use language like "simple", "easy", etc.? + + +## Recommendations + + + +### Information architecture + +### New user content + +### Content maintainability & site mechanics + +### Content creation processes + +### Inclusive language + + +# Contributor documentation + + +_PROJECT_ is a **graduated** project of CNCF. This means that the project should have [*very high*][criteria-doc] standards for documentation. + +_PROJECT_ is an **incubating** project of CNCF. This means that the project should be [*developing*][criteria-doc] professional-quality documentation alongside the project code. + +| Criterion | Rating (1-5) | +| --- | ----------------- | +| Communication methods documented | (rating value) | +| Beginner friendly issue backlog | (rating value) | +| “New contributor” getting started content | (rating value) | +| Project governance documentation | (rating value) | + + + + +## Comments + + + +The following sections contain brief assessments of each element of the Contributor Documentation rubric. + + + +### Communication methods documented + +One of the easiest ways to attract new contributors is making sure they know how to reach you. + +We evaluate on the following: + +* Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website? +* Is there a direct link to your GitHub organization/repository? +* Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings? +* Are mailing lists documented? + +### Beginner friendly issue backlog + +We evaluate on the following: + +* Are docs issues well-triaged? +* Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)? +* Are issues well-documented (i.e., more than just a title)? +* Are issues maintained for staleness? + +### New contributor getting started content + +Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump in easily? + +We evaluate on the following: + +* Do you have a community repository or section on your website? +* Is there a document specifically for new contributors/your first contribution? +* Do new users know where to get help? + +### Project governance documentation + +One of the CNCF’s core project values is open governance. + +We evaluate on the following: + +* Is project governance clearly documented? + +## Recommendations + + + +### Communication methods documented + +### Beginner friendly issue backlog + +### New contributor getting started content + +### Project governance documentation + + +# Website and infrastructure + + +_PROJECT_ is a **graduated** project of CNCF. This means that the project should have [*very high*][criteria-doc] standards for documentation. + +_PROJECT_ is an **incubating** project of CNCF. This means that the project should be [*developing*][criteria-doc] professional-quality documentation alongside the project code. + +| Criterion | Rating (1-5) | +| --- | ---------------- | +| Single-source for all files | (rating value) | +| Meets min website req. (for maturity level) | (rating value) | +| Usability, accessibility, and design | (rating value) | +| Branding and design | (rating value) | +| Case studies/social proof | (rating value) | +| SEO, Analytics, and site-local search | (rating value) | +| Maintenance planning | (rating value) | +| A11y plan & implementation | (rating value) | +| Mobile-first plan & impl. | (rating value) | +| HTTPS access & HTTP redirect | (rating value) | +| Google Analytics 4 for production only | (rating value) | +| Indexing allowed for production server only | (rating value) | +| Intra-site / local search | (rating value) | +| Account custodians are documented | (rating value) | + + + + +## Comments + + + +The following sections contain brief assessments of each element of the Website and documentation infrastructure rubric. + + + + +### Single-source requirement + +Source files for _all website pages_ should reside in a single repo. +Among other problems, keeping source files in two places: +- confuses contributors +- requires you to keep two sources in sync +- increases the likelihood of errors +- makes it more complicated to generate the documentation from source files + +Ideally, all website files should be in the **website repo** itself. +Alternatively, files should be brought into the website repo via [git +submodules][git-submodules]. + +If a project chooses to keep source files in multiple repos, they need a clearly +documented strategy for managing mirrored files and new contributions. + +### Minimal website requirements + +Listed here are the minimal website requirements for projects based on their [maturity level][maturity-level], either incubating or graduated. (These are the only two levels for which a tech docs analysis can be requested.) + +| Criterion | Incubating Requirement | Graduated Requirement | +| --- | --- | --- | +| [Website guidelines][website-guidelines] | All guidelines satisfied | All guidelines satisfied | +| [Docs analysis][analysis-doc] (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | +| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | +| **Project doc**: hosting | Hosted directly | Hosted directly | +| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | + +[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[website-guidelines]: /../../resources/website-guidelines-checklist.md +[maturity-level]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +[cncf-servicedesk]: https://servicedesk.cncf.io + +### Usability, accessibility and devices + +Most CNCF websites are accessed from mobile and other non-desktop devices at least 10-20% of the time. Planning for this early in your website's design will be much less effort than retrofitting a desktop-first design. + +* Is the website usable from mobile? +* Are doc pages readable? +* Are all / most website features accessible from mobile -- such as the top-nav, + site search and in-page table of contents? +* Might a [mobile-first] design make sense for your project? + +[mobile-first]: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first + +Plan for suitable [accessibility][] measures for your website. For example: + +* Are color contrasts significant enough for color-impaired readers? +* Are most website features usable using a keyboard only? +* Does text-to-speech offer listeners a good experience? + +It is up to each project to set their own guidelines. + +[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility + +### Branding and design + +CNCF seeks to support enterprise-ready open source software. A key aspect of +this is branding and marketing. + +We evaluate on the following: + +* Is there an easily recognizable brand for the project (logo + color scheme) + clearly identifiable? +* Is the brand used across the website consistently? +* Is the website’s typography clean and well-suited for reading? + +### Case studies/social proof + +One of the best ways to advertise an open source project is to show other organizations using it. + +We evaluate on the following: + +* Are there case studies available for the project and are they documented on the website? +* Are there user testimonials available? +* Is there an active project blog? +* Are there community talks for the project and are they present on the website? +* Is there a logo wall of users/participating organizations? + + +### SEO, Analytics and site-local search + +SEO helps users find your project and it's documentation, and analytics helps +you monitor site traffic and diagnose issues like page 404s. Intra-site search, +while optional, can offer your readers a site-focused search results. + +We evaluate on the following: + +* Analytics: + - Is analytics enabled for the production server? + - Is analytics disabled for all other deploys? + - If your project used Google Analytics, have you migrated to GA4? + - Can Page-not-found (404) reports easily be generated from you site + analytics? Provide a sample of the site's current top-10 404s. +* Is site indexing supported for the production server, while disabled for + website previews and builds for non-default branches? +* Is local intra-site search available from the website? +* Are the current custodian(s) of the following accounts clearly documented: + analytics, Google Search Console, site-search (such as Google CSE or Algolia) + + +### Maintenance planning + +Website maintenance is an important part of project success, especially when project maintainers aren’t web developers. + +We evaluate on the following: + +* Is your website tooling well supported by the community (i.e., Hugo with the + Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) +* Are you actively cultivating website maintainers from within the community? +* Are site build times reasonable? +* Do site maintainers have adequate permissions? + +### Other + +* Is your website accessible via HTTPS? +* Does HTTP access, if any, redirect to HTTPS? + +## Recommendations + + + +### Single-source requirement + +### Minimal website requirements + +### Usability, accessibility and devices + +### Branding and design + +### Case studies/social proof + +### SEO, Analytics and site-local search + +### Maintenance planning + +### Other + + + + +[project-website]: _PROJECT-WEBSITE_ +[project-doc-website]: _PROJECT-DOC-URL_ +[criteria-doc]: ./criteria.md +[implementation-template]: ./implementation-template.md +[issues-template]: ./issue-template.md +[umbrella-template]: ./umbrella-issue-template.md +[implementation-doc]: ./_PROJECT_-implementation.md +[issues-doc]: ./_PROJECT_-issues.md +[project-heading]: #project-documentation +[contributor-heading]: #contributor-documentation +[website-heading]: #website +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 +[website-guidelines]: ../../resources/website-guidelines-checklist.md + diff --git a/analysis/analysis-tools/criteria.md b/analysis/analysis-tools/criteria.md index f74d25e..138ad68 100644 --- a/analysis/analysis-tools/criteria.md +++ b/analysis/analysis-tools/criteria.md @@ -137,10 +137,12 @@ Examples: ### Single-source requirement -Source files for _all website pages_ should reside in a _single_ repo. -Otherwise, having source files in two places will confuse contributors (who -won't know which file(s) to update) and you'll run the risk of losing updates -— [as has happened already][otel-changes-lost]. +Source files for _all website pages_ should reside in a single repo. +Among other problems, keeping source files in two places: +- confuses contributors +- requires you to keep two sources in sync +- increases the likelihood of errors +- makes it more complicated to generate the documentation from source files Ideally, all website files should be in the **website repo** itself. Alternatively, files should be brought into the website repo via [git @@ -149,9 +151,6 @@ submodules][]. If a project chooses to keep source files in multiple repos, they need a clearly documented strategy for managing mirrored files and new contributions. -[otel-changes-lost]: https://github.com/open-telemetry/opentelemetry.io/issues/673 -[git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules - ### Minimal website requirements Listed here are the _minimal_ website requirements for projects based on their @@ -220,6 +219,7 @@ Plan for suitable [accessibility][] measures for your website. For example: It is up to each project to set their own guidelines. [accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility + ### Branding CNCF seeks to support enterprise-ready open source software. A key aspect of diff --git a/analysis/analysis-tools/howto.md b/analysis/analysis-tools/howto.md index fdaff04..f4c56d9 100644 --- a/analysis/analysis-tools/howto.md +++ b/analysis/analysis-tools/howto.md @@ -1,51 +1,111 @@ -# CNCF Project documentation assessments +# CNCF TechDocs Analysis How-To + +## Audience + +This document is for members of the CNCF TechDocs team, including contractors or consultants, who need to conduct or assist with an analysis of a CNCF open-source project's technical documentation. -**Who this document is for:** Members of the CNCF Techdocs team. This document provides guidance and a template on executing documentation assessments for CNCF projects. ## Purpose -The aim of a documentation assessment is to: +The goals of a CNCF technical documentation analysis are to: + +- Examine the current project technical documentation and website against the CNCF's analysis framework, as described in the doc analysis [criteria](./criteria.md). +- Compare the documentation against the current or proposed maturity level for the overall project. +- Recommends a program of key improvements with the largest return on investment. These improvements are documented as *recommendations* in the analysis document and expanded in a companion [implementation plan](./implementation-template.md) and [issues backlog](./umbrella-issue-template.md). + + +## Doing a Tech Docs Analysis + +The tech docs analysis consists of some repository bookkeeping (Prerequisites), then of three overall tasks: + +1. Write the analysis document: Evaluate the existing project documentation with respect to the project maturity level (or proposed maturity level, if the analysis is associated with an upgrade reqeust). Identify gaps with CNCF criteria. Write general recommendations to close the largest and most important gaps. +2. Write the implementation plan: Decompose the recommendations to specific improvement suggestions. These can be additions or revisions to the docs; reorganization; website infrastructure changes; or any other work that will close the gaps. Make suggestions specific (if you propose reorganizing a section, for example, provide an outline) but provide enough information that a contributor could solve the problem differently if they have a different idea (make it clear that your proposed outline is only one possible reorganization, e.g.). +3. Write the issue backlog. + +Finally, there are follow-up steps including creating GitHub issues and a pull request, and getting approval from project maintainers. + +### Prerequisites + +This process assumes you have some familiarity with GitHub repositories and pull requests (PRs). + +1. Clone the [CNCF tech docs repository](https://github.com/cncf/techdocs). +1. Create a branch for the analysis. +1. In the new branch, create a directory for the analysis in the CNCF tech docs /analysis directory. Name the directory `00NN-_PROJECT_`, where *NN* is the next index available in the directory (check for PRs as well, if someone else is working on tech doc analyses), and where _PROJECT_ is a short but not abbreviated project name. For example, for Kubernetes _PROJECT_ would be *kubernetes*, not *k8s*. +1. Copy and rename the analysis doc templates from the `/analysis/analysis-tools` directory as follows: `analysis-template.md` > `_PROJECT_-analysis.md`; `implementation-template.md` > `_PROJECT_-implementation.md`; and `umbrella-issue-template.md` > `_PROJECT_-issues.md`. + + +### Writing the Analysis document + +Edit `_PROJECT_-analysis.md` and follow these steps to complete the first step, the analysis: + +1. Define the scope of the analysis. Edit "Scope of analysis" to reflect URLs and repositories included and excluded from the analysis. +1. Review the in-scope URLs and repositories for compliance with the rubric criteria. Note any gaps, as well as any areas that exceed criteria or are exceptionally well executed. I find it easiest to do this separately for each of the three areas of concern (project doc, contributor doc, website), making a pass through the documentation once for each section (Information architecture, New user content, Content maintainability, etc.). Don't worry about a numerical score during this step; instead, note how the documentation complies, or not, with each criterion with respect to the project maturity level (or proposed maturity level, if the analysis is part of a petition for upgrade). Write comments to note the most important gaps and best-executed features of the documentation. +1. Assign ratings to each criterion based on your comments and compliance with the maturity level expectations in the rubric. The ratings are self-explanatory. Keep in mind that "needs improvement" or "meets standards" is with respect to the current (or proposed) maturity level. +1. Write recommendations. The template implies that you'll do this for every criterion; the "Recommendations" headings mirror the "Comments" headings. However, if some alternative framework makes more sense, use that. For example, it might be that two or three of the product documentation criteria are improved by reorganizing the documentation. In this case, rather than repeat the recommendation to reorganize in each section, write a single recommendation and explain how it improves all the areas. This is the first step in moving from the analysis to specific, actionable, time-bound backlog items. + +#### General tips + +Things to keep in mind while doing the analysis: +- Look for: + - Quick wins – low-effort changes that would have a major impact. + - Large, systemic issues that you can organize a number of issues around. + - The two or three most important issues that impede documentation effectiveness. + - Anything the project does exceptionally well. We can call these out as examples in other evaluations! +- Don't get bogged down in detail when writing comments. Include enough detail that you can describe how to implement a suggested solution. A sentence or two is sufficient for most issues. +- Keep in mind the overall goal of the technical documentation: to make its users more effective. Focus on issues that get in the way of that goal. +- It is not necessary to come up with a recommendation in every case, especially for elements that are satisfactory or if a recommendation would result in minimal improvement. +- Don't worry about grammar and style if they don't affect documentation effectiveness. If writing style impedes understanding, make a note; otherwise move on. An exception: Insist that tasks and procedures be written as clear, step-by-step instructions. +- Some of the criteria, especially around contributor documentation, project governance, and website infrastructure, are essentially check-boxes. These you can quickly investigate, note, and move on. Spend more time analyzing the effectiveness of the project documentation. + +#### Common issues + +Many common issues seem to come about because open-source software documentation is written by software developers while they are writing the software. This results in documentation that: +1. Is organized around features, not users and use cases. +2. Explains technical concepts well, including architecture and design decisions. +3. Contains complete reference information for APIs, CLIs, and configuration parameters. +4. Has missing or incomplete user-oriented "how-to" explanations and operational procedures. + +You may or may not find the following issues in your analysis, but it's worth keeping them in mind: +- Ambiguity around user roles. +- Missing or unclear task-based documentation. +- Assumptions about the reader's level of knowledge. +- Organization that buries or scatters important information, especially tasks and procedures. +- Missing or unclear new-user workflows. + +### Writing the implementation plan -- Measure against the CNCF’s standards for documentation -- Recommend areas to improve -- Provide examples of great documentation as reference -- Identify key areas which will net the largest improvement if addressed +Write the implementation plan. Edit the `_PROJECT_-implementation.md` file. -**What an assessment is** +The gist of the implementation plan is to break down the recommendations in the analysis document. This is an intermediate stage between general recommendations and the issues backlog. For small projects and where the recommendations are independent and time-bound, an implementation plan might not be necessary and you can move straight to writing the backlog. -- An overview with specific recommendations -- As short as possible – err on the side of bulleted lists -- Geared at providing actionable feedback (litmus test: could you turn a piece of feedback into a backlog issue with little extra work?) +If you do write an implementation plan, start with recommendations in the analysis document. Rewrite the recommendations, making them more specific, with a suggested (but not mandatory) implementation. For example, if you recommend reorganizing the documentation, provide a suggested outline, along with an explanation of the reason for the reorg. -**What it isn’t** +### Writing an issues backlog -- Full lists of exhaustive solutions for each and every issue with a website -- Fluffy and unspecific -- Judgmental +Write an issues backlog. Edit `_PROJECT_-issues.md`. -## Assessment criteria and examples +The goal of writing an issues backlog is to offer project contributors the opportunity to make the recommended changes. -See [Assessment definitions and reference examples](criteria.md). +Rewrite each action in the implementation plan. If possible, break large actions into smaller issues. Each issue should be: +- Independent. As much as possible, no issue should have another issue as a prerequisite. A contributor should be able to choose an issue, resolve it, and close it without reference to any other issue. +- Time-bound. A contributor should be able to complete an issue in a reasonably short time, say a few hours or a couple of days at most. -**Doing an assessment** +Make the suggested solution even more specific. At this point, the issue should almost be a recipe for making the doc improvement, with the caveat that a contributor is not required to implement the solution as suggested in the issue. -When doing an assessment: +## Next Steps -1. Locate a project’s main documentation repository and any community/contributor/org/governance repositories -Review all documentation available & the website (if present). +### Including supporting documentation -2. Note: +If you have supporting material that might be helpful to a contributor working on the documentation issues, include them in the directory with the other documents. For example, you might inventory the existing tech doc pages in a spreadsheet; in this case, include a CSV file of the inventory. - - Any quick wins - - Larger, systemic issues at play - - Main issues to fix - - What the project does exceptionally well! +### Creating a pull request -3. Draft the assessment using the template provided +If you have not created a pull request with the analysis documents, do so now. Tag project maintainers and CNCF documentation staff, and ask for comments. -4. Send it to the CNCF techdocs team for a review +### Getting contributor feedback -5. Send it to the project maintainers and schedule a zoom meeting to discuss with them in person. +If you haven't met with the project's maintainers yet, do so before you create the issues in GitHub. Ideally you'd like to have a Zoom meeting with any interested parties to get feedback on the analysis and implementation plan. -6. PR to the techdocs repository in this directory for archiving +### Creating GitHub issues +Enter the backlog issues from the issues document into the project documentation GitHub repository using the format in the umbrella-issues-template.md and issues-template.md files. Create one GitHub issue per backlog issue, and create an umbrella issue that contains a checklist item for each issue. diff --git a/analysis/analysis-tools/implementation-template.md b/analysis/analysis-tools/implementation-template.md new file mode 100644 index 0000000..d73f4d9 --- /dev/null +++ b/analysis/analysis-tools/implementation-template.md @@ -0,0 +1,35 @@ +--- +title: Implementing _PROJECT_ Doc Improvements +tags: _PROJECT_ +--- + +# Introduction + +This document provides actionable suggestions for improving the _PROJECT_ technical documentation. + +For an analysis and general discussion of recommendations on _PROJECT_ technical documentation, see [_PROJECT_-analysis.md][]. + +## Recommendations, requirements, and best practices + +This analysis measures documentation against CNCF project maturity standards and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, recommendations are based on documentation best practices as understood by the reviewers. The recommended implementations represent the reviewers' experience with how to apply those best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-keywords], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. + +The top-level documentation recommendations for this project are: + + + +# High-level action 1 + +## Issue 1 + +## Issue 2 + +# High-level action 2 + +## Issue 1 + +## Issue 2 + + + + +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 diff --git a/analysis/analysis-tools/issue-template.md b/analysis/analysis-tools/issue-template.md new file mode 100644 index 0000000..6b8a071 --- /dev/null +++ b/analysis/analysis-tools/issue-template.md @@ -0,0 +1,40 @@ +--- +title: _PROJECT_ Issue +tags: _PROJECT_ +--- + + + +# Overview + + + +Audience: + +Type: + +# Context + + + +This issue tracks recommended changes resulting from an analysis of the etcd documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/assessments/00NN-project/ + +# Possible Implementation + + + +Related material in the current doc: +- https://github.com/_PROJECT_/website/tree/main/content/en/docs/v3.5/tutorials + + + +Suggested changes: + +Use the following outline to write a procedure for each task: + +- Prerequisites (bullet list of prerequisite conditions, if any) +- Procedure + 1. Step 1 (keep steps discrete and atomic. Put command-line input and expected output in a code block.) + 2. Step 2 ... +- Result (optional; describe output or side effects if they're notable or unexpected.) + diff --git a/analysis/analysis-tools/template.md b/analysis/analysis-tools/template.md deleted file mode 100644 index 03c42f0..0000000 --- a/analysis/analysis-tools/template.md +++ /dev/null @@ -1,112 +0,0 @@ -# Assessment template - -Prepared by: \ ([@add-link-to-your-github-id](https://github.com/cncf/techdocs))
-Date: 2021-mm-dd - -## Introduction - -This document assesses the quality and completeness of a project's documentation and website (if present). - -This document: - -- Measures existing documentation quality against the CNCF’s standards -- Recommends specific and general improvements -- Provides examples of great documentation as reference -- Identifies key improvements with the largest return on investment - - -## How this document works - -The assessment is divided into three sections: - -- **Project documentation:** for end users of the project; aimed at people who intend to use it -- **Contributor documentation:** for new and existing contributors to the project -- **Website:** branding, website structure, and maintainability - -Each section rates content based on different [criteria](criteria.md). - - -## Project documentation - -| Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Information architecture | | | | | | -| New user content | | | | | | -| Content maintainability | | | | | | -| Content creation processes | | | | | | - -Scale: -- 1 = (Is not present or requires significant work) -- 3 = (Is present, but needs work) -- 5 = (Is executed extremely well or no improvement required) - -**Comments** - -_Provide comments for each rating above, 1-2 sentences max, bullet point list_ - -**Recommendations** - -_Provide a list of recommendations to improve in this area_ - - -## Contributor documentation - -| Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Communication methods documented | | | | | | -| Beginner friendly issue backlog | | | | | | -| “New contributor” getting started content | | | | | | -| Project governance documentation | | | | | | - -Scale: -- 1 = (Is not present or requires significant work) -- 3 = (Is present, but needs work) -- 5 = (Is executed extremely well or no improvement required) - -**Comments** - -_Provide comments for each rating above, 1-2 sentences max, bullet point list_ - -**Recommendations** - -_Provide a list of recommendations to improve in this area_ - - -## Website - -| Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Single-source for all files | | | | | | -| Meets min website req. (for maturity level) | | | | | | -| Branding and design | | | | | | -| Case studies/social proof | | | | | | -| Maintenance planning | | | | | | -| A11y plan & implementation | | | | | | -| Mobile-first plan & impl. | | | | | | -| HTTPS access & HTTP redirect | | | | | | -| Google Analytics 4 for production only | | | | | | -| Indexing allowed for production server only | | | | | | -| Intra-site / local search | | | | | | -| Account custodians are documented | | | | | | - -Scale: -- 1 = (Is not present or requires significant work) -- 3 = (Is present, but needs work) -- 5 = (Is executed extremely well or no improvement required) - -**Comments** - -_Provide comments for each rating above, 1-2 sentences max, bullet point list_ -_Include a list of the top 404s, as reported through analytics or a search console._ - -**Recommendations** - -_Provide a list of recommendations to improve in this area_ - - -## Recommendations - -_From the recommendations above, lis the top 1-3 concerns for this particular project and expand on them in enough detail that you could either:_ - - _Pass the work off to a contractor or other member of the CNCF techdocs team_ - - _Write a GitHub issue for the project team and place it in the backlog and someone not involved in the docs assessment process could execute on it_ - diff --git a/analysis/analysis-tools/umbrella-issue-template.md b/analysis/analysis-tools/umbrella-issue-template.md new file mode 100644 index 0000000..27e2006 --- /dev/null +++ b/analysis/analysis-tools/umbrella-issue-template.md @@ -0,0 +1,31 @@ +--- +title: _PROJECT_ Umbrella Issue +tags: _PROJECT_ +--- + +# Overview + + + + + + + +This issue tracks recommended changes resulting from an analysis of the _PROJECT_ documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/assessments/00NN-project/ + +The CNCF etcd documentation effort is tracked in the CNCF Tech Docs repo: +https://github.com/cncf/techdocs/issues/NNN + +# Issues + +This is a list of issues representing the recommended work on the _PROJECT_ website and technical documentation. + +## Issue: Item 1 + + + +- [ ] https://github.com/project/repo/issues/NNN + +## Issue: Item 2 + + From 9f2938b132519142c2ca3ce9c381c515bd108b6d Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Wed, 15 May 2024 10:46:41 -0700 Subject: [PATCH 04/10] Apply suggestions from code review Co-authored-by: Patrice Chalin Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Patrice Chalin --- README.md | 14 +++----------- TechDoc-Assistance-Program.md | 29 +++++++++++++++-------------- 2 files changed, 18 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 57e1c37..0c421ff 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ This repository holds resources provided by the CNCF Technical Documentation team. The repo contains the following directories: - `analysis` contains instructions, templates, and criteria for requesting and performing an analysis of an OSS project's website and technical documentation. Completed analyses are stored here as well. -- `resources` contains information that OSS teams can use to set up a documentation project as suggested by the Tech Docs team. +- `resources` contains information that OSS teams can use to set up a documentation project as suggested by the TechDocs team. ## CNCF TechDocs team @@ -33,14 +33,6 @@ Zoom link: https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872?pas We store ongoing meeting notes in a [Google doc](https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/). -## The Technical Documentation Assistance Program +## Assistance program for technical documentation -The CNCF Tech Doc team has created a program to assist CNCF-affiliated projects in creating effective documentation. [`TechDoc-Assistance-Program.md`](./TechDoc-Assistance-Program.md) contains an outline of this program. - -Project maintainers are asked to understand that: -- Project documentation resources are *always* underestimated. -- Documentation is as much a real part of a project as code. -- Effective documentation requires a real commitment of resources. -- The TechDoc Assistance Program exists to help maintainers allocate these resources effectively, but cannot write documentation for you or 'fix' documentation problems. - -We're passionate about good documentation and we want to help your project succeed. Please work with us by taking this part of your project seriously. +The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see TechDocs [Assistance program](./TechDoc-Assistance-Program.md). diff --git a/TechDoc-Assistance-Program.md b/TechDoc-Assistance-Program.md index 04754ee..802be15 100644 --- a/TechDoc-Assistance-Program.md +++ b/TechDoc-Assistance-Program.md @@ -1,8 +1,8 @@ -# Technical Documentation Assistance Program +# Assistance program for technical documentation This document outlines the Cloud Native Computing Foundation (CNCF) Technical Documentation Assistance Program (the Program), a service offered by CNCF Tech Docs for evaluating and improving an OSS project's technical documentation. The process is designed to: -1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level](analysis/analysis-tools/criteria.md. (Often, documentation help is requested when a project requests promotion to a new maturity level.) +1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level](analysis/analysis-tools/criteria.md). Often, projects request an analysis in support of promotion to a new maturity level. 1. Recommend changes that will reduce the gap between the documentation and the maturity of the overall project. 1. Expand on the recommended changes in an implementation plan. 1. Break down the implementation into a documentation project backlog comprising a GitHub Issues list. @@ -15,41 +15,42 @@ Some level of familiarity with the technical documentation process is required t - Work effectively with technical writers - Draft technical documentation (for non-writers) -- Improve the chances of a good outcome from the Tech Doc Assistance Program +- Get the best results out of the Assistance Program -For this reason, CNCF offers free training on documentation essentials for project contributors and maintainers. To get the most from the Technical Documentation Assistance Program, project contributors should do the training *before* engaging a documentation specialist to complete the documentation analysis. +For this reason, CNCF offers free training on documentation essentials for project contributors and maintainers. To get the most from the Assistance Program, project contributors are encouraged to do the training *before* engaging a documentation specialist to complete the documentation analysis. The training program consists of the following online courses. Anyone can sign up for and complete the courses at their own pace. 1. [Open Source Technical Documentation Essentials (LFC111)](https://training.linuxfoundation.org/training/open-source-technical-documentation-essentials-lfc111/) 1. [Creating Effective Documentation for Developers (LFC112)](https://training.linuxfoundation.org/training/creating-effective-documentation-for-developers-lfc112/) -## Phase 1: Documentation Analysis +## Phase 1: Documentation analysis -A technical writer (on CNCF staff or on contract) analyzes the documentation. Based on the standards developed by the CNCF Tech Docs program, the writer: +A technical writer (on CNCF staff or on contract) analyzes the documentation. Based on the standards developed as part of the CNCF TechDocs program, the writer: -1. Estimates the maturity level of the documentation compared to the current or desired maturity level of the software project, based on a number of criteria in three categories, using a rubric developed by CNCF. The categories are: +1. Estimates the maturity level of the documentation compared to the current or desired maturity level of the software project using a rubric developed by CNCF. The rubric is divided into three categories: +2. ``` 1. Project documentation: The end-user documentation for the project's work product, typically (but not always) an application, API, protocol, or some other software product. 1. Contributor documentation: Documentation about the project, aimed at project contributors and describing procedures, infrastructure, and customs for doing project work. This includes artifacts that define procedures and governance; recruit, orient, and train project contributors; and name responsible parties (project leaders, often generically called *maintainers*). 1. Website: The technical infrastructure behind the documentation and the project's web presence, including website generation, versioning, SEO, analytics, and security. 1. Collaborates with project leadership to identify user roles and objectives for software users. -1. Proposes changes, if necessary, to the organization and content of the documentation to close gaps with the proposed maturity level. -1. Writes an implementation plan describing improvements that address the gaps identified in the analysis. +1. Proposes changes, if necessary, to the organization and content of the documentation to close gaps with the target maturity level. +1. Writes an implementation plan describing improvements that address the gaps identified by the analysis. -## Phase 2: Backlog Creation +## Phase 2: Backlog creation Once a high-level improvement plan has been written and approved, the tech writer analyzes the proposed changes to create a backlog of actionable, individual writing assignments and other tasks to improve the documentation. These tasks should have two primary characteristics: - As much as possible, they should be independent of each other so they can be completed in any order by any combination of contributors; and -- They should be time-constrained. If possible, large tasks should be broken down into smaller, independent tasks that require hours, not days, to complete. +- They should be time-constrained. If possible, large tasks should be broken down into smaller, independent tasks that require hours or days rather than weeks to complete. -## Phase 3: Documentation Improvement +## Phase 3: Documentation improvement Community members work on the issues created in the previous phase. Ideally, tech writers are available to advise contributors and edit work, especially if the contributing community members are not trained technical writers. Remember that the training courses in Phase 0 are available to prepare contributors with general knowledge of the process. We know that recruiting contributors to write documentation can be difficult. While this is largely the responsibility of the project leadership, CNCF is actively working on ways to encourage doc contributions. For example, creating a backlog of time-bounded issues is an attempt to lower barriers, both psychological and logistical, to documentation creation and maintenance. -## Phase 4: Impact Analysis +## Phase 4: Impact analysis -Measurement is vital to any process improvement effort, and this is currently the weakest point of the TechDoc Assistance Program. We do no offer any tools to measure the impact of doc improvements, although we can assure you that they are profound. Projects are encouraged to collect metrics on documentation effectiveness. +Projects are encouraged to collect metrics (using Google analytics and page feedback data) on documentation usage as a means of assessing the effectiveness of documentation improvements. As a basic gauge the effectiveness of the documentation effort, projects can track the issue backlog. This can provide a guide to progress on leveling the documentation maturity to that of the project. From f2b4d9e8c0da68ebf52ae402f23b7d67e7bbce37 Mon Sep 17 00:00:00 2001 From: David Welsch Date: Thu, 16 May 2024 14:11:41 -0700 Subject: [PATCH 05/10] Renamed directories, made recommended changes from reviews. Signed-off-by: David Welsch Signed-off-by: Patrice Chalin --- README.md | 8 +- {analysis => analyses}/0001-contour.md | 0 {analysis => analyses}/0002-notary-project.md | 0 {analysis => analyses}/0003-krator.md | 0 {analysis => analyses}/0004-tremor.md | 0 {analysis => analyses}/0005-fluxcd.md | 0 {analysis => analyses}/0006-gateway-api.md | 0 {analysis => analyses}/0007-porter.md | 0 .../0008-backstage/README.md | 0 .../0008-backstage/backstage-analysis.md | 0 .../0008-backstage/backstage-doc-survey.csv | 0 .../0008-backstage/backstage-glossary.md | 0 .../backstage-implementation.md | 0 .../backstage-insights-summary.md | 0 .../0008-backstage/backstage-issues.md | 0 .../0008-backstage/user-roles.md | 0 {analysis => analyses}/0009-in-toto/README.md | 0 .../0009-in-toto/in-toto-analysis.md | 0 .../0009-in-toto/in-toto-doc-issues.md | 0 .../0009-in-toto/in-toto-implementation.md | 0 .../0009-in-toto/survey-of-existing-doc.md | 0 {analysis => analyses}/0010-etcd/README.md | 0 .../0010-etcd/etcd-analysis.md | 0 .../0010-etcd/etcd-implementation.md | 0 .../0010-etcd/etcd-issues.md | 0 {analysis => analyses}/0011-keda/README.md | 0 .../0011-keda/keda-analysis.md | 0 .../0011-keda/keda-implementation.md | 0 .../0011-keda/keda-issues.md | 0 analyses/README.md | 34 +++++++++ analysis/README.md | 71 ------------------ docs/README.md | 4 + {resources => docs}/analytics.md | 0 {analysis/analysis-tools => docs}/criteria.md | 0 {analysis/analysis-tools => docs}/howto.md | 0 {resources => docs}/hugo-and-docsy.md | 0 .../images/folder-based-etcd.png | Bin .../images/subdomain-based-k8s.png | Bin {resources => docs}/localization/README.md | 0 {resources => docs}/netlify-domains-setup.md | 0 {resources => docs}/repo-setup.md | 0 .../searching-documentation.md | 0 {resources => docs}/services.md | 0 .../versioning-documentation.md | 0 .../website-guidelines-checklist.md | 0 resources/README.md | 15 +++- .../analysis-template.md | 0 .../implementation-template.md | 0 .../issue-template.md | 0 .../umbrella-issue-template.md | 0 ...stance-Program.md => techdoc-assistance.md | 5 +- 51 files changed, 59 insertions(+), 78 deletions(-) rename {analysis => analyses}/0001-contour.md (100%) rename {analysis => analyses}/0002-notary-project.md (100%) rename {analysis => analyses}/0003-krator.md (100%) rename {analysis => analyses}/0004-tremor.md (100%) rename {analysis => analyses}/0005-fluxcd.md (100%) rename {analysis => analyses}/0006-gateway-api.md (100%) rename {analysis => analyses}/0007-porter.md (100%) rename {analysis => analyses}/0008-backstage/README.md (100%) rename {analysis => analyses}/0008-backstage/backstage-analysis.md (100%) rename {analysis => analyses}/0008-backstage/backstage-doc-survey.csv (100%) rename {analysis => analyses}/0008-backstage/backstage-glossary.md (100%) rename {analysis => analyses}/0008-backstage/backstage-implementation.md (100%) rename {analysis => analyses}/0008-backstage/backstage-insights-summary.md (100%) rename {analysis => analyses}/0008-backstage/backstage-issues.md (100%) rename {analysis => analyses}/0008-backstage/user-roles.md (100%) rename {analysis => analyses}/0009-in-toto/README.md (100%) rename {analysis => analyses}/0009-in-toto/in-toto-analysis.md (100%) rename {analysis => analyses}/0009-in-toto/in-toto-doc-issues.md (100%) rename {analysis => analyses}/0009-in-toto/in-toto-implementation.md (100%) rename {analysis => analyses}/0009-in-toto/survey-of-existing-doc.md (100%) rename {analysis => analyses}/0010-etcd/README.md (100%) rename {analysis => analyses}/0010-etcd/etcd-analysis.md (100%) rename {analysis => analyses}/0010-etcd/etcd-implementation.md (100%) rename {analysis => analyses}/0010-etcd/etcd-issues.md (100%) rename {analysis => analyses}/0011-keda/README.md (100%) rename {analysis => analyses}/0011-keda/keda-analysis.md (100%) rename {analysis => analyses}/0011-keda/keda-implementation.md (100%) rename {analysis => analyses}/0011-keda/keda-issues.md (100%) create mode 100644 analyses/README.md delete mode 100644 analysis/README.md create mode 100644 docs/README.md rename {resources => docs}/analytics.md (100%) rename {analysis/analysis-tools => docs}/criteria.md (100%) rename {analysis/analysis-tools => docs}/howto.md (100%) rename {resources => docs}/hugo-and-docsy.md (100%) rename {resources => docs}/images/folder-based-etcd.png (100%) rename {resources => docs}/images/subdomain-based-k8s.png (100%) rename {resources => docs}/localization/README.md (100%) rename {resources => docs}/netlify-domains-setup.md (100%) rename {resources => docs}/repo-setup.md (100%) rename {resources => docs}/searching-documentation.md (100%) rename {resources => docs}/services.md (100%) rename {resources => docs}/versioning-documentation.md (100%) rename {resources => docs}/website-guidelines-checklist.md (100%) rename {analysis/analysis-tools => resources}/analysis-template.md (100%) rename {analysis/analysis-tools => resources}/implementation-template.md (100%) rename {analysis/analysis-tools => resources}/issue-template.md (100%) rename {analysis/analysis-tools => resources}/umbrella-issue-template.md (100%) rename TechDoc-Assistance-Program.md => techdoc-assistance.md (92%) diff --git a/README.md b/README.md index 0c421ff..13b69d0 100644 --- a/README.md +++ b/README.md @@ -35,4 +35,10 @@ We store ongoing meeting notes in a [Google doc](https://docs.google.com/documen ## Assistance program for technical documentation -The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see TechDocs [Assistance program](./TechDoc-Assistance-Program.md). +The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance-program][]. + +[assistance-program]: ./techdoc-assistance.md + +### Resources + +The `docs/` directory contains collected resources for building websites and developing documentation, including recommended tools and practices, how-tos, and evaluation checklists. \ No newline at end of file diff --git a/analysis/0001-contour.md b/analyses/0001-contour.md similarity index 100% rename from analysis/0001-contour.md rename to analyses/0001-contour.md diff --git a/analysis/0002-notary-project.md b/analyses/0002-notary-project.md similarity index 100% rename from analysis/0002-notary-project.md rename to analyses/0002-notary-project.md diff --git a/analysis/0003-krator.md b/analyses/0003-krator.md similarity index 100% rename from analysis/0003-krator.md rename to analyses/0003-krator.md diff --git a/analysis/0004-tremor.md b/analyses/0004-tremor.md similarity index 100% rename from analysis/0004-tremor.md rename to analyses/0004-tremor.md diff --git a/analysis/0005-fluxcd.md b/analyses/0005-fluxcd.md similarity index 100% rename from analysis/0005-fluxcd.md rename to analyses/0005-fluxcd.md diff --git a/analysis/0006-gateway-api.md b/analyses/0006-gateway-api.md similarity index 100% rename from analysis/0006-gateway-api.md rename to analyses/0006-gateway-api.md diff --git a/analysis/0007-porter.md b/analyses/0007-porter.md similarity index 100% rename from analysis/0007-porter.md rename to analyses/0007-porter.md diff --git a/analysis/0008-backstage/README.md b/analyses/0008-backstage/README.md similarity index 100% rename from analysis/0008-backstage/README.md rename to analyses/0008-backstage/README.md diff --git a/analysis/0008-backstage/backstage-analysis.md b/analyses/0008-backstage/backstage-analysis.md similarity index 100% rename from analysis/0008-backstage/backstage-analysis.md rename to analyses/0008-backstage/backstage-analysis.md diff --git a/analysis/0008-backstage/backstage-doc-survey.csv b/analyses/0008-backstage/backstage-doc-survey.csv similarity index 100% rename from analysis/0008-backstage/backstage-doc-survey.csv rename to analyses/0008-backstage/backstage-doc-survey.csv diff --git a/analysis/0008-backstage/backstage-glossary.md b/analyses/0008-backstage/backstage-glossary.md similarity index 100% rename from analysis/0008-backstage/backstage-glossary.md rename to analyses/0008-backstage/backstage-glossary.md diff --git a/analysis/0008-backstage/backstage-implementation.md b/analyses/0008-backstage/backstage-implementation.md similarity index 100% rename from analysis/0008-backstage/backstage-implementation.md rename to analyses/0008-backstage/backstage-implementation.md diff --git a/analysis/0008-backstage/backstage-insights-summary.md b/analyses/0008-backstage/backstage-insights-summary.md similarity index 100% rename from analysis/0008-backstage/backstage-insights-summary.md rename to analyses/0008-backstage/backstage-insights-summary.md diff --git a/analysis/0008-backstage/backstage-issues.md b/analyses/0008-backstage/backstage-issues.md similarity index 100% rename from analysis/0008-backstage/backstage-issues.md rename to analyses/0008-backstage/backstage-issues.md diff --git a/analysis/0008-backstage/user-roles.md b/analyses/0008-backstage/user-roles.md similarity index 100% rename from analysis/0008-backstage/user-roles.md rename to analyses/0008-backstage/user-roles.md diff --git a/analysis/0009-in-toto/README.md b/analyses/0009-in-toto/README.md similarity index 100% rename from analysis/0009-in-toto/README.md rename to analyses/0009-in-toto/README.md diff --git a/analysis/0009-in-toto/in-toto-analysis.md b/analyses/0009-in-toto/in-toto-analysis.md similarity index 100% rename from analysis/0009-in-toto/in-toto-analysis.md rename to analyses/0009-in-toto/in-toto-analysis.md diff --git a/analysis/0009-in-toto/in-toto-doc-issues.md b/analyses/0009-in-toto/in-toto-doc-issues.md similarity index 100% rename from analysis/0009-in-toto/in-toto-doc-issues.md rename to analyses/0009-in-toto/in-toto-doc-issues.md diff --git a/analysis/0009-in-toto/in-toto-implementation.md b/analyses/0009-in-toto/in-toto-implementation.md similarity index 100% rename from analysis/0009-in-toto/in-toto-implementation.md rename to analyses/0009-in-toto/in-toto-implementation.md diff --git a/analysis/0009-in-toto/survey-of-existing-doc.md b/analyses/0009-in-toto/survey-of-existing-doc.md similarity index 100% rename from analysis/0009-in-toto/survey-of-existing-doc.md rename to analyses/0009-in-toto/survey-of-existing-doc.md diff --git a/analysis/0010-etcd/README.md b/analyses/0010-etcd/README.md similarity index 100% rename from analysis/0010-etcd/README.md rename to analyses/0010-etcd/README.md diff --git a/analysis/0010-etcd/etcd-analysis.md b/analyses/0010-etcd/etcd-analysis.md similarity index 100% rename from analysis/0010-etcd/etcd-analysis.md rename to analyses/0010-etcd/etcd-analysis.md diff --git a/analysis/0010-etcd/etcd-implementation.md b/analyses/0010-etcd/etcd-implementation.md similarity index 100% rename from analysis/0010-etcd/etcd-implementation.md rename to analyses/0010-etcd/etcd-implementation.md diff --git a/analysis/0010-etcd/etcd-issues.md b/analyses/0010-etcd/etcd-issues.md similarity index 100% rename from analysis/0010-etcd/etcd-issues.md rename to analyses/0010-etcd/etcd-issues.md diff --git a/analysis/0011-keda/README.md b/analyses/0011-keda/README.md similarity index 100% rename from analysis/0011-keda/README.md rename to analyses/0011-keda/README.md diff --git a/analysis/0011-keda/keda-analysis.md b/analyses/0011-keda/keda-analysis.md similarity index 100% rename from analysis/0011-keda/keda-analysis.md rename to analyses/0011-keda/keda-analysis.md diff --git a/analysis/0011-keda/keda-implementation.md b/analyses/0011-keda/keda-implementation.md similarity index 100% rename from analysis/0011-keda/keda-implementation.md rename to analyses/0011-keda/keda-implementation.md diff --git a/analysis/0011-keda/keda-issues.md b/analyses/0011-keda/keda-issues.md similarity index 100% rename from analysis/0011-keda/keda-issues.md rename to analyses/0011-keda/keda-issues.md diff --git a/analyses/README.md b/analyses/README.md new file mode 100644 index 0000000..99d212e --- /dev/null +++ b/analyses/README.md @@ -0,0 +1,34 @@ +# CNCF TechDocs Analysis for OSS Projects + +## Purpose + +The goals of a CNCF technical documentation analysis are to: + +- Examine the current project technical documentation and website against the CNCF's analysis framework, as described in the doc analysis [criteria](./criteria.md). +- Compare the documentation against the current or proposed maturity level for the overall project. +- Recommends a program of key improvements with the largest return on investment. These improvements are documented as *recommendations* in the analysis document and expanded in a companion [implementation plan](./implementation-template.md) and [issues backlog](./umbrella-issue-template.md). + +## Audience + +Analyses are written for the purpose of improving a project's documentation and are available for anyone to read. Among the intended benefits to project stakeholders are these: + +- **Project maintainers** can gain a critical overview of the technical documentation to plan work on the project's documentation. This work can increase the effectiveness of the project software, speed adoption, and improve user satisfaction. +- **Project contributors** can take on the recommended backlog issues to improve the documentation. + +The analyses also provide information of value to organizations with an interest in promoting open source software: + +- **CNCF Foundation members** can see what benefits can (and cannot) be expected of a documentation improvement effort. +- **Members of other open-source software foundations** can use these analyses as a model for their own documentation improvement processes. (Please contact the Cloud Native Computing Foundation to discuss licensing and permission of analysis templates and tools.) + +## Contents + +This directory contains completed analyses of the technical documentation for selected CNCF incubating and graduated software projects. + +The analyses are in one of two formats depending on when they were written. Earlier analyses (**0001** - **0007**) are Markdown files, each of which is the sole artifact of the analysis. + +Subsequent analyses (**0008-** forward) each has its own directory containing three analysis artifacts: + - `projectname-analysis.md` evaluates the project documentation and provides comments and recommendations in a manner very similar to the Round 1 tech doc assessments. This document is based on the analysis template and accompanying criteria developed for the Round 1. + - `projectname-implementation.md` provides concrete actions that can be implemented by project contributors. Its focus is on specific, achievable work that will have a strong positive impact on document effectiveness. + - `projectname-issues.md` is a backlog of improvement actions, meant to be entered as GitHub Issues, derived from `projectname-implementation.md`. + +Each directory might also contain other documents, such as CSV-formatted surveys of documentation pages. diff --git a/analysis/README.md b/analysis/README.md deleted file mode 100644 index dc2f65c..0000000 --- a/analysis/README.md +++ /dev/null @@ -1,71 +0,0 @@ -# CNCF TechDocs Analysis for OSS Projects - -## Purpose - -The goals of a CNCF technical documentation analysis are to: - -- Examine the current project technical documentation and website against the CNCF's analysis framework, as described in the doc analysis [criteria](./criteria.md). -- Compare the documentation against the current or proposed maturity level for the overall project. -- Recommends a program of key improvements with the largest return on investment. These improvements are documented as *recommendations* in the analysis document and expanded in a companion [implementation plan](./implementation-template.md) and [issues backlog](./umbrella-issue-template.md). - -## Contents - -In this directory: - -- **Project Analyses**: `analysis` contains analyses of the technical documentation for selected CNCF incubating and graduated software projects. -- **Analysis Tools**: `analysis-tools` contains instructions, templates, analysis criteria, and background information to enable a mid- to senior-level technical writer to perform an analysis independently with some support from the CNCF tech docs staff. - -### Project Analyses - -Completed analyses are contained in the `analysis` directory. - -There are two rounds of projects, *Round 1* and *Round 2*. - -#### Round 1 - -Analyses **0001** - **0007** are a first round of projects completed as "assessments" through the CNCF Help Desk. The `000N-projectname.md` file is the sole artifact of the assessment in each case. The last one was added in May 2023. - -#### Round 2 - -Subsequent analyses were commissioned starting in November 2023. Each has its own directory, `00NN-projectname`, containing three analysis artifacts: - - `projectname-analysis.md` evaluates the project documentation and provides comments and recommendations in a manner very similar to the Round 1 tech doc assessments. This document is based on the analysis template and accompanying criteria developed for the Round 1. - - `projectname-implementation.md` provides concrete actions that can be implemented by project contributors. Its focus is on specific, achievable work that will have a strong positive impact on document effectiveness. - - `projectname-issues.md` is a backlog of improvement actions, meant to be entered as GitHub Issues, derived from `projectname-implementation.md`. - -### Analysis Tools - -Templates and instructions for doing the analyses are contained in the `analysis-tools` directory. - -#### Audience - -This directory is for primarily for members of the CNCF TechDocs team, including contractors or consultants, who need to conduct or assist with an analysis of a CNCF open-source project's technical documentation. Readers in other roles can also benefit from understanding the guidelines in this directory: - -- **Project maintainers** can learn how improved technical documentation can increase the effectiveness of the project software, speed adoption, and improve user satisfaction. -- **CNCF Foundation members** can learn what benefits can (and cannot) be expected of a documentation improvement effort. -- **Members of other open-source software foundations** can use the analysis tools as a model, in whole or in part, for their own documentation improvement processes. (Please contact the Cloud Native Computing Foundation to discuss licensing and permission.) -- **Project contributors** can learn what factors go into improving technical documentation and what is expected of contributors who work on project documentation issues. - -#### Contents - -Use the guidelines and templates in this directory to perform a documentation analysis for CNCF. These materials provide: -- A relatively objective set of criteria (a "rubric") for evaluating existing documentation and website content, infrastructure, and support. -- An attempt to make the documentation analysis appropriate to the current (or proposed) maturity level for the overall project. -- Emphasis on effective documentation that serves all users associated with the project. - -##### How-to - -`howto.md` contains instructions for requesting, writing, and consuming an analysis. - -##### Criteria - -`criteria.md` describes the criteria used to evaluate a project's technical documentation and website. These criteria are also referred to as a "rubric" elsewhere in this repo. The criteria are unchanged between the first and second round of analyses. - -##### Templates - -These are templates for the analysis artifacts. - -- **Analysis Template**: `analysis-template.md` is the main analysis template, based on the work of the original 2021-23 tech docs assessments. -- **Implementation Plan**: The implementation plan, represented in `implementation-template.md`, is an intermediate step between the analysis and the issues backlog, meant as an aid to digesting the analysis recommendations into actionable issues. -- **Issues**: This is the final backlog of recommended changes to the documentation, meant to be transferred directly into the GitHub Issues of the project documentation repo. There are two templates: - - `issue-template.md` is a template for individual issues that can be use to create issues in GitHub. - - `umbrella-issue-template.md` can be used to create an umbrella issue in GitHub, and can also be used as a template for a `_PROJECT_-issues.md` document to be included in the analysis pull request. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..6f832a2 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,4 @@ +# CNCF Techdocs how-tos + +This directory contains documentation on how the CNCF TechDocs team does things. While its intent is for the CNCF TechDocs team's use, we encourage project maintainers to use these documents if you find them helpful! + diff --git a/resources/analytics.md b/docs/analytics.md similarity index 100% rename from resources/analytics.md rename to docs/analytics.md diff --git a/analysis/analysis-tools/criteria.md b/docs/criteria.md similarity index 100% rename from analysis/analysis-tools/criteria.md rename to docs/criteria.md diff --git a/analysis/analysis-tools/howto.md b/docs/howto.md similarity index 100% rename from analysis/analysis-tools/howto.md rename to docs/howto.md diff --git a/resources/hugo-and-docsy.md b/docs/hugo-and-docsy.md similarity index 100% rename from resources/hugo-and-docsy.md rename to docs/hugo-and-docsy.md diff --git a/resources/images/folder-based-etcd.png b/docs/images/folder-based-etcd.png similarity index 100% rename from resources/images/folder-based-etcd.png rename to docs/images/folder-based-etcd.png diff --git a/resources/images/subdomain-based-k8s.png b/docs/images/subdomain-based-k8s.png similarity index 100% rename from resources/images/subdomain-based-k8s.png rename to docs/images/subdomain-based-k8s.png diff --git a/resources/localization/README.md b/docs/localization/README.md similarity index 100% rename from resources/localization/README.md rename to docs/localization/README.md diff --git a/resources/netlify-domains-setup.md b/docs/netlify-domains-setup.md similarity index 100% rename from resources/netlify-domains-setup.md rename to docs/netlify-domains-setup.md diff --git a/resources/repo-setup.md b/docs/repo-setup.md similarity index 100% rename from resources/repo-setup.md rename to docs/repo-setup.md diff --git a/resources/searching-documentation.md b/docs/searching-documentation.md similarity index 100% rename from resources/searching-documentation.md rename to docs/searching-documentation.md diff --git a/resources/services.md b/docs/services.md similarity index 100% rename from resources/services.md rename to docs/services.md diff --git a/resources/versioning-documentation.md b/docs/versioning-documentation.md similarity index 100% rename from resources/versioning-documentation.md rename to docs/versioning-documentation.md diff --git a/resources/website-guidelines-checklist.md b/docs/website-guidelines-checklist.md similarity index 100% rename from resources/website-guidelines-checklist.md rename to docs/website-guidelines-checklist.md diff --git a/resources/README.md b/resources/README.md index 6f832a2..cd9f414 100644 --- a/resources/README.md +++ b/resources/README.md @@ -1,4 +1,15 @@ -# CNCF Techdocs how-tos +# TechDoc Analysis Templates -This directory contains documentation on how the CNCF TechDocs team does things. While its intent is for the CNCF TechDocs team's use, we encourage project maintainers to use these documents if you find them helpful! +This directory contains templates for analyzing a CNCF project's documentation. +## Contents + +Use the templates in this directory to perform a documentation analysis for CNCF. These materials provide: +- A relatively objective set of criteria (a "rubric") for evaluating existing documentation and website content, infrastructure, and support. +- An attempt to make the documentation analysis appropriate to the current (or proposed) maturity level for the overall project. +- Emphasis on effective documentation that serves all users associated with the project. + +Resources for completing a documentation analysis, including a [how-to][] guide and analysis [criteria][], are in the `docs` directory. + +[how-to]: ../docs/howto.md +[criteria]: ../docs/criteria.md \ No newline at end of file diff --git a/analysis/analysis-tools/analysis-template.md b/resources/analysis-template.md similarity index 100% rename from analysis/analysis-tools/analysis-template.md rename to resources/analysis-template.md diff --git a/analysis/analysis-tools/implementation-template.md b/resources/implementation-template.md similarity index 100% rename from analysis/analysis-tools/implementation-template.md rename to resources/implementation-template.md diff --git a/analysis/analysis-tools/issue-template.md b/resources/issue-template.md similarity index 100% rename from analysis/analysis-tools/issue-template.md rename to resources/issue-template.md diff --git a/analysis/analysis-tools/umbrella-issue-template.md b/resources/umbrella-issue-template.md similarity index 100% rename from analysis/analysis-tools/umbrella-issue-template.md rename to resources/umbrella-issue-template.md diff --git a/TechDoc-Assistance-Program.md b/techdoc-assistance.md similarity index 92% rename from TechDoc-Assistance-Program.md rename to techdoc-assistance.md index 802be15..8c79c60 100644 --- a/TechDoc-Assistance-Program.md +++ b/techdoc-assistance.md @@ -2,7 +2,7 @@ This document outlines the Cloud Native Computing Foundation (CNCF) Technical Documentation Assistance Program (the Program), a service offered by CNCF Tech Docs for evaluating and improving an OSS project's technical documentation. The process is designed to: -1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level](analysis/analysis-tools/criteria.md). Often, projects request an analysis in support of promotion to a new maturity level. +1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level](docs/criteria.md). Often, projects request an analysis in support of promotion to a new maturity level. 1. Recommend changes that will reduce the gap between the documentation and the maturity of the overall project. 1. Expand on the recommended changes in an implementation plan. 1. Break down the implementation into a documentation project backlog comprising a GitHub Issues list. @@ -29,7 +29,6 @@ The training program consists of the following online courses. Anyone can sign u A technical writer (on CNCF staff or on contract) analyzes the documentation. Based on the standards developed as part of the CNCF TechDocs program, the writer: 1. Estimates the maturity level of the documentation compared to the current or desired maturity level of the software project using a rubric developed by CNCF. The rubric is divided into three categories: -2. ``` 1. Project documentation: The end-user documentation for the project's work product, typically (but not always) an application, API, protocol, or some other software product. 1. Contributor documentation: Documentation about the project, aimed at project contributors and describing procedures, infrastructure, and customs for doing project work. This includes artifacts that define procedures and governance; recruit, orient, and train project contributors; and name responsible parties (project leaders, often generically called *maintainers*). 1. Website: The technical infrastructure behind the documentation and the project's web presence, including website generation, versioning, SEO, analytics, and security. @@ -52,5 +51,3 @@ We know that recruiting contributors to write documentation can be difficult. Wh ## Phase 4: Impact analysis Projects are encouraged to collect metrics (using Google analytics and page feedback data) on documentation usage as a means of assessing the effectiveness of documentation improvements. - -As a basic gauge the effectiveness of the documentation effort, projects can track the issue backlog. This can provide a guide to progress on leveling the documentation maturity to that of the project. From 0a855c8f9b3c8baade9e428f1d30d76750e2cb23 Mon Sep 17 00:00:00 2001 From: David Welsch Date: Thu, 16 May 2024 14:26:29 -0700 Subject: [PATCH 06/10] Temporarily renamed analyses back to assessments to merge in-toto change Signed-off-by: David Welsch Signed-off-by: Patrice Chalin --- {analyses => assessments}/0001-contour.md | 0 {analyses => assessments}/0002-notary-project.md | 0 {analyses => assessments}/0003-krator.md | 0 {analyses => assessments}/0004-tremor.md | 0 {analyses => assessments}/0005-fluxcd.md | 0 {analyses => assessments}/0006-gateway-api.md | 0 {analyses => assessments}/0007-porter.md | 0 {analyses => assessments}/0008-backstage/README.md | 0 {analyses => assessments}/0008-backstage/backstage-analysis.md | 0 {analyses => assessments}/0008-backstage/backstage-doc-survey.csv | 0 {analyses => assessments}/0008-backstage/backstage-glossary.md | 0 .../0008-backstage/backstage-implementation.md | 0 .../0008-backstage/backstage-insights-summary.md | 0 {analyses => assessments}/0008-backstage/backstage-issues.md | 0 {analyses => assessments}/0008-backstage/user-roles.md | 0 {analyses => assessments}/0009-in-toto/README.md | 0 {analyses => assessments}/0009-in-toto/in-toto-analysis.md | 0 {analyses => assessments}/0009-in-toto/in-toto-doc-issues.md | 0 {analyses => assessments}/0009-in-toto/in-toto-implementation.md | 0 {analyses => assessments}/0009-in-toto/survey-of-existing-doc.md | 0 {analyses => assessments}/0010-etcd/README.md | 0 {analyses => assessments}/0010-etcd/etcd-analysis.md | 0 {analyses => assessments}/0010-etcd/etcd-implementation.md | 0 {analyses => assessments}/0010-etcd/etcd-issues.md | 0 {analyses => assessments}/0011-keda/README.md | 0 {analyses => assessments}/0011-keda/keda-analysis.md | 0 {analyses => assessments}/0011-keda/keda-implementation.md | 0 {analyses => assessments}/0011-keda/keda-issues.md | 0 {analyses => assessments}/README.md | 0 29 files changed, 0 insertions(+), 0 deletions(-) rename {analyses => assessments}/0001-contour.md (100%) rename {analyses => assessments}/0002-notary-project.md (100%) rename {analyses => assessments}/0003-krator.md (100%) rename {analyses => assessments}/0004-tremor.md (100%) rename {analyses => assessments}/0005-fluxcd.md (100%) rename {analyses => assessments}/0006-gateway-api.md (100%) rename {analyses => assessments}/0007-porter.md (100%) rename {analyses => assessments}/0008-backstage/README.md (100%) rename {analyses => assessments}/0008-backstage/backstage-analysis.md (100%) rename {analyses => assessments}/0008-backstage/backstage-doc-survey.csv (100%) rename {analyses => assessments}/0008-backstage/backstage-glossary.md (100%) rename {analyses => assessments}/0008-backstage/backstage-implementation.md (100%) rename {analyses => assessments}/0008-backstage/backstage-insights-summary.md (100%) rename {analyses => assessments}/0008-backstage/backstage-issues.md (100%) rename {analyses => assessments}/0008-backstage/user-roles.md (100%) rename {analyses => assessments}/0009-in-toto/README.md (100%) rename {analyses => assessments}/0009-in-toto/in-toto-analysis.md (100%) rename {analyses => assessments}/0009-in-toto/in-toto-doc-issues.md (100%) rename {analyses => assessments}/0009-in-toto/in-toto-implementation.md (100%) rename {analyses => assessments}/0009-in-toto/survey-of-existing-doc.md (100%) rename {analyses => assessments}/0010-etcd/README.md (100%) rename {analyses => assessments}/0010-etcd/etcd-analysis.md (100%) rename {analyses => assessments}/0010-etcd/etcd-implementation.md (100%) rename {analyses => assessments}/0010-etcd/etcd-issues.md (100%) rename {analyses => assessments}/0011-keda/README.md (100%) rename {analyses => assessments}/0011-keda/keda-analysis.md (100%) rename {analyses => assessments}/0011-keda/keda-implementation.md (100%) rename {analyses => assessments}/0011-keda/keda-issues.md (100%) rename {analyses => assessments}/README.md (100%) diff --git a/analyses/0001-contour.md b/assessments/0001-contour.md similarity index 100% rename from analyses/0001-contour.md rename to assessments/0001-contour.md diff --git a/analyses/0002-notary-project.md b/assessments/0002-notary-project.md similarity index 100% rename from analyses/0002-notary-project.md rename to assessments/0002-notary-project.md diff --git a/analyses/0003-krator.md b/assessments/0003-krator.md similarity index 100% rename from analyses/0003-krator.md rename to assessments/0003-krator.md diff --git a/analyses/0004-tremor.md b/assessments/0004-tremor.md similarity index 100% rename from analyses/0004-tremor.md rename to assessments/0004-tremor.md diff --git a/analyses/0005-fluxcd.md b/assessments/0005-fluxcd.md similarity index 100% rename from analyses/0005-fluxcd.md rename to assessments/0005-fluxcd.md diff --git a/analyses/0006-gateway-api.md b/assessments/0006-gateway-api.md similarity index 100% rename from analyses/0006-gateway-api.md rename to assessments/0006-gateway-api.md diff --git a/analyses/0007-porter.md b/assessments/0007-porter.md similarity index 100% rename from analyses/0007-porter.md rename to assessments/0007-porter.md diff --git a/analyses/0008-backstage/README.md b/assessments/0008-backstage/README.md similarity index 100% rename from analyses/0008-backstage/README.md rename to assessments/0008-backstage/README.md diff --git a/analyses/0008-backstage/backstage-analysis.md b/assessments/0008-backstage/backstage-analysis.md similarity index 100% rename from analyses/0008-backstage/backstage-analysis.md rename to assessments/0008-backstage/backstage-analysis.md diff --git a/analyses/0008-backstage/backstage-doc-survey.csv b/assessments/0008-backstage/backstage-doc-survey.csv similarity index 100% rename from analyses/0008-backstage/backstage-doc-survey.csv rename to assessments/0008-backstage/backstage-doc-survey.csv diff --git a/analyses/0008-backstage/backstage-glossary.md b/assessments/0008-backstage/backstage-glossary.md similarity index 100% rename from analyses/0008-backstage/backstage-glossary.md rename to assessments/0008-backstage/backstage-glossary.md diff --git a/analyses/0008-backstage/backstage-implementation.md b/assessments/0008-backstage/backstage-implementation.md similarity index 100% rename from analyses/0008-backstage/backstage-implementation.md rename to assessments/0008-backstage/backstage-implementation.md diff --git a/analyses/0008-backstage/backstage-insights-summary.md b/assessments/0008-backstage/backstage-insights-summary.md similarity index 100% rename from analyses/0008-backstage/backstage-insights-summary.md rename to assessments/0008-backstage/backstage-insights-summary.md diff --git a/analyses/0008-backstage/backstage-issues.md b/assessments/0008-backstage/backstage-issues.md similarity index 100% rename from analyses/0008-backstage/backstage-issues.md rename to assessments/0008-backstage/backstage-issues.md diff --git a/analyses/0008-backstage/user-roles.md b/assessments/0008-backstage/user-roles.md similarity index 100% rename from analyses/0008-backstage/user-roles.md rename to assessments/0008-backstage/user-roles.md diff --git a/analyses/0009-in-toto/README.md b/assessments/0009-in-toto/README.md similarity index 100% rename from analyses/0009-in-toto/README.md rename to assessments/0009-in-toto/README.md diff --git a/analyses/0009-in-toto/in-toto-analysis.md b/assessments/0009-in-toto/in-toto-analysis.md similarity index 100% rename from analyses/0009-in-toto/in-toto-analysis.md rename to assessments/0009-in-toto/in-toto-analysis.md diff --git a/analyses/0009-in-toto/in-toto-doc-issues.md b/assessments/0009-in-toto/in-toto-doc-issues.md similarity index 100% rename from analyses/0009-in-toto/in-toto-doc-issues.md rename to assessments/0009-in-toto/in-toto-doc-issues.md diff --git a/analyses/0009-in-toto/in-toto-implementation.md b/assessments/0009-in-toto/in-toto-implementation.md similarity index 100% rename from analyses/0009-in-toto/in-toto-implementation.md rename to assessments/0009-in-toto/in-toto-implementation.md diff --git a/analyses/0009-in-toto/survey-of-existing-doc.md b/assessments/0009-in-toto/survey-of-existing-doc.md similarity index 100% rename from analyses/0009-in-toto/survey-of-existing-doc.md rename to assessments/0009-in-toto/survey-of-existing-doc.md diff --git a/analyses/0010-etcd/README.md b/assessments/0010-etcd/README.md similarity index 100% rename from analyses/0010-etcd/README.md rename to assessments/0010-etcd/README.md diff --git a/analyses/0010-etcd/etcd-analysis.md b/assessments/0010-etcd/etcd-analysis.md similarity index 100% rename from analyses/0010-etcd/etcd-analysis.md rename to assessments/0010-etcd/etcd-analysis.md diff --git a/analyses/0010-etcd/etcd-implementation.md b/assessments/0010-etcd/etcd-implementation.md similarity index 100% rename from analyses/0010-etcd/etcd-implementation.md rename to assessments/0010-etcd/etcd-implementation.md diff --git a/analyses/0010-etcd/etcd-issues.md b/assessments/0010-etcd/etcd-issues.md similarity index 100% rename from analyses/0010-etcd/etcd-issues.md rename to assessments/0010-etcd/etcd-issues.md diff --git a/analyses/0011-keda/README.md b/assessments/0011-keda/README.md similarity index 100% rename from analyses/0011-keda/README.md rename to assessments/0011-keda/README.md diff --git a/analyses/0011-keda/keda-analysis.md b/assessments/0011-keda/keda-analysis.md similarity index 100% rename from analyses/0011-keda/keda-analysis.md rename to assessments/0011-keda/keda-analysis.md diff --git a/analyses/0011-keda/keda-implementation.md b/assessments/0011-keda/keda-implementation.md similarity index 100% rename from analyses/0011-keda/keda-implementation.md rename to assessments/0011-keda/keda-implementation.md diff --git a/analyses/0011-keda/keda-issues.md b/assessments/0011-keda/keda-issues.md similarity index 100% rename from analyses/0011-keda/keda-issues.md rename to assessments/0011-keda/keda-issues.md diff --git a/analyses/README.md b/assessments/README.md similarity index 100% rename from analyses/README.md rename to assessments/README.md From 836c4636c0d2118e7f4f76a88e994fa876eb65bf Mon Sep 17 00:00:00 2001 From: David Welsch Date: Thu, 16 May 2024 15:07:15 -0700 Subject: [PATCH 07/10] Final (hopefully) changes to the techdoc analysis materials. Directory structure chnages included. Signed-off-by: David Welsch Signed-off-by: Patrice Chalin --- techdoc-assistance.md => assistance.md | 0 docs/analysis/README.md | 10 ++++++++++ docs/{ => analysis}/criteria.md | 0 docs/{ => analysis}/howto.md | 0 {resources => docs/analysis/resources}/README.md | 0 .../analysis/resources}/analysis-template.md | 0 .../analysis/resources}/implementation-template.md | 0 .../analysis/resources}/issue-template.md | 0 .../analysis/resources}/umbrella-issue-template.md | 0 9 files changed, 10 insertions(+) rename techdoc-assistance.md => assistance.md (100%) create mode 100644 docs/analysis/README.md rename docs/{ => analysis}/criteria.md (100%) rename docs/{ => analysis}/howto.md (100%) rename {resources => docs/analysis/resources}/README.md (100%) rename {resources => docs/analysis/resources}/analysis-template.md (100%) rename {resources => docs/analysis/resources}/implementation-template.md (100%) rename {resources => docs/analysis/resources}/issue-template.md (100%) rename {resources => docs/analysis/resources}/umbrella-issue-template.md (100%) diff --git a/techdoc-assistance.md b/assistance.md similarity index 100% rename from techdoc-assistance.md rename to assistance.md diff --git a/docs/analysis/README.md b/docs/analysis/README.md new file mode 100644 index 0000000..7c5e414 --- /dev/null +++ b/docs/analysis/README.md @@ -0,0 +1,10 @@ +# TechDoc Analysis + +## Contents + +This directory contains instructions and criteria for completing a documentation analysis, including a [how-to][] guide and analysis [criteria][]. + +Templates for the analyses are in the resources directory. + +[how-to]: ./howto.md +[criteria]: ./criteria.md diff --git a/docs/criteria.md b/docs/analysis/criteria.md similarity index 100% rename from docs/criteria.md rename to docs/analysis/criteria.md diff --git a/docs/howto.md b/docs/analysis/howto.md similarity index 100% rename from docs/howto.md rename to docs/analysis/howto.md diff --git a/resources/README.md b/docs/analysis/resources/README.md similarity index 100% rename from resources/README.md rename to docs/analysis/resources/README.md diff --git a/resources/analysis-template.md b/docs/analysis/resources/analysis-template.md similarity index 100% rename from resources/analysis-template.md rename to docs/analysis/resources/analysis-template.md diff --git a/resources/implementation-template.md b/docs/analysis/resources/implementation-template.md similarity index 100% rename from resources/implementation-template.md rename to docs/analysis/resources/implementation-template.md diff --git a/resources/issue-template.md b/docs/analysis/resources/issue-template.md similarity index 100% rename from resources/issue-template.md rename to docs/analysis/resources/issue-template.md diff --git a/resources/umbrella-issue-template.md b/docs/analysis/resources/umbrella-issue-template.md similarity index 100% rename from resources/umbrella-issue-template.md rename to docs/analysis/resources/umbrella-issue-template.md From 438386fc24a52eb8cc3969f455d1db1d90364a6e Mon Sep 17 00:00:00 2001 From: David Welsch Date: Thu, 16 May 2024 15:12:29 -0700 Subject: [PATCH 08/10] Reverting CSV file. Signed-off-by: David Welsch Signed-off-by: Patrice Chalin --- .../0008-backstage/backstage-doc-survey.csv | 370 +++++++++--------- 1 file changed, 185 insertions(+), 185 deletions(-) diff --git a/assessments/0008-backstage/backstage-doc-survey.csv b/assessments/0008-backstage/backstage-doc-survey.csv index 775fe92..c23af5c 100644 --- a/assessments/0008-backstage/backstage-doc-survey.csv +++ b/assessments/0008-backstage/backstage-doc-survey.csv @@ -1,185 +1,185 @@ -Title,URL,Doc Type,User Role,Use Case,Doc Suite Position,Comment -Overview,,,,,, -What is Backstage?,https://backstage.io/docs/overview/what-is-backstage,concept,adopter,decision,Technical Overview,Introductory -Architecture overview,https://backstage.io/docs/overview/architecture-overview,concept,administrator,deployment,Architecture Overview,"Substantial, in-depth view of architecture" -Roadmap,https://backstage.io/docs/overview/roadmap,concept,administrator,"deployment, maintenance",Release Notes,Should be updated frequently; move to release notes -Vision,https://backstage.io/docs/overview/vision,concept,"contributor, adopter","strategy, sales",White Paper,"Short, high-level statement of vision." -The Spotify Story,https://backstage.io/docs/overview/background,concept,"contributor, adopter","strategy, sales",White Paper,Background info. Move to website. -Strategies for adopting,https://backstage.io/docs/overview/adopting,concept,adopter,decision,Overview,"Would be useful in adoption go/no-go decisions, and in adoption/deployment/configuration." -Release and Versioning Policy,https://backstage.io/docs/overview/versioning-policy,concept,"contributor, adopter","contribute, maintenance","Release Notes, Contributor Instructions", -Backstage Threat Model,https://backstage.io/docs/overview/threat-model,concept,administrator,deployment,"Architecture Overview, Installation Guide",Required by admin to set up security posture -Support and community,https://backstage.io/docs/overview/support,reference,any,"support, decision, contrib","RN, FAQ, KB, Overviews",Should be available to any interested user from almost anywhere -Backstage Glossary,https://backstage.io/docs/overview/glossary,reference,any,any,KB,"Should be available generally, esp. to new users" -Logo assets,https://backstage.io/docs/overview/logos,reference,"contributor, adopter",contribute,,Reference info for contributing designer -Getting Started,,,,,, -Getting Started,https://backstage.io/docs/getting-started/,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Installation instructions -Getting Started configuring Backstage,https://backstage.io/docs/getting-started/configuration,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide; Getting Started Guide","Split: Configuring database, authentication (installation); Creating your first components (getting started)" -Create an App,https://backstage.io/docs/getting-started/create-an-app,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","How to set up an instance. Might need two setup procedures, one for users and one for admins." -Configuring App with plugins,https://backstage.io/docs/getting-started/configure-app-with-plugins,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Should go in a chapter of the install guide devoted to installing existing plugins -Customize the look-and-feel of your App,https://backstage.io/docs/getting-started/app-custom-theme,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Should be a chapter of the install guide -Backstage homepage - Setup and Customization,https://backstage.io/docs/getting-started/homepage,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide", -Keeping Backstage Updated,https://backstage.io/docs/getting-started/keeping-backstage-updated,task,administrator,"installation, setup, config",IS&C; RN,Upgrade procedures in admin guide; particular upgrades in release notes -Key Concepts,https://backstage.io/docs/getting-started/concepts,reference,administrator,,,This is a list of software dependencies. Needed by admin. Upgrades needed by each release in RN. -Contributors,https://backstage.io/docs/getting-started/contributors,task,contributor,contribute,Contributor setup guide,"Contributor guide can be limited to GitHub, or a separate contributor guide put on the website" -Getting Involved,https://backstage.io/docs/getting-started/getting-involved,reference,contributor,contribute,Contributor overview,This material belongs in the intro to a contributor guide -Backstage Project Structure,https://backstage.io/docs/getting-started/project-structure,reference,contributor,contribute,Contributor reference,"Structure of the GitHub repo, annotated. Reference for contributors." -Local Development,,,,,, -Overview,https://backstage.io/docs/local-dev/cli-overview,concept,administrator,deployment,Architecture Overview,"This is part of the architecture overview, a discussion of the components of the CLI" -Build System,https://backstage.io/docs/local-dev/cli-build-system,concept,administrator,deployment,Architecture Overview,Description of how the Build system works; belongs in the Architecture Overview -Commands,https://backstage.io/docs/local-dev/cli-commands,reference,administrator; user,use,API Reference,"This is a command reference for the CLI, which seems to be a tool for doing builds of components in Backstage" -Linking in Local Packages,https://backstage.io/docs/local-dev/linking-local-packages,task,user,use,Recipe,This is a technique for testing a build. Goes in a recipe book or use and testing guide. -Debugging Backstage,https://backstage.io/docs/local-dev/debugging,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Description of how to change the logging level in Backstage. -Core Features,,,,,, -Overview,https://backstage.io/docs/features/software-catalog/,task,user,use,User Guide,Basic catalog tasks. Also a short intro to the catalog (conceptual). -The Life of an Entity,https://backstage.io/docs/features/software-catalog/life-of-an-entity,concept,administrator; user,deployment,Architecture Overview,Detailed description of data ingestion when importing an entity. -Catalog Configuration,https://backstage.io/docs/features/software-catalog/configuration,concept,administrator; user,deployment,Architecture Overview,Additional information for ingesting entities -System Model,https://backstage.io/docs/features/software-catalog/system-model,concept,user,use,User Guide,Describes the model behind various entities. Some of this could go in the Knowledge Base as well maybe. -YAML File Format,https://backstage.io/docs/features/software-catalog/descriptor-format,reference,user,use,User Guide,"Reference to entity descriptors, with examples in JSON." -Entity References,https://backstage.io/docs/features/software-catalog/references,reference,user,use,User Guide,Description of how entities reference other entities -Well-known Annotations,https://backstage.io/docs/features/software-catalog/well-known-annotations,reference,user,use,User Guide,More on entities -Well-known Relations,https://backstage.io/docs/features/software-catalog/well-known-relations,reference,user,use,User Guide,More on entities -Well-known Statuses,https://backstage.io/docs/features/software-catalog/well-known-statuses,reference,user,use,User Guide,More on entities -Extending the model,https://backstage.io/docs/features/software-catalog/extending-the-model,reference,user,use,User Guide,More on entities -External integrations,https://backstage.io/docs/features/software-catalog/external-integrations,reference,user,use,User Guide,More on entities -Catalog Customization,https://backstage.io/docs/features/software-catalog/catalog-customization,task,administrator,deployment,"Installation, Setup, and Config Guide",How to customize the entity display page. A recipe for the site admin -API,https://backstage.io/docs/features/software-catalog/software-catalog-api,reference,administrator; user,use,API Reference,The Entity API. Could be teased apart into a true reference and a set of recipes. -Creating the Catalog Graph,https://backstage.io/docs/features/software-catalog/creating-the-catalog-graph,reference,user,use,User Guide,Describes the catalog model and what is displayed in the UI -Overview,https://backstage.io/docs/features/kubernetes/,concept,user,use,Kubernetes plugin guide,Intro to the 2 Kubernetes plugins -Installation,https://backstage.io/docs/features/kubernetes/installation,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Could go in the main install guide or in a separate k8s guide -Configuration,https://backstage.io/docs/features/kubernetes/configuration,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide","Continuation of k8s install instructions, but contains mostly descriptions of the config settings" -Kubernetes Authentication,https://backstage.io/docs/features/kubernetes/authentication,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Describes how to authenticate k8s on various services. -Troubleshooting,https://backstage.io/docs/features/kubernetes/troubleshooting,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",What to do if k8s doesn’t show up as a service entity -Proxy,https://backstage.io/docs/features/kubernetes/proxy,task,"contributor, admin","installation, setup, config","Installation, Setup, and Config Guide",How to set up a k8s proxy endpoint. Known limitation should be moved to a release note. -Overview,https://backstage.io/docs/features/software-templates/,task,administrator; user,getting started,Getting Started Guide (“Hello World”),“Disable Register Existing Component button” is an admin task that should be in the config documentation -Configuration,https://backstage.io/docs/features/software-templates/configuration,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to configure a template -Adding your own Templates,https://backstage.io/docs/features/software-templates/adding-templates,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to add a template -Writing Templates,https://backstage.io/docs/features/software-templates/writing-templates,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",The anatomy of a template and how to write one. -Input Examples,https://backstage.io/docs/features/software-templates/input-examples,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Anatomy of template input components. Could be a mini-cookbook or a section of the config instructions for Templates -Builtin actions,https://backstage.io/docs/features/software-templates/builtin-actions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Describes how to migrate a fetch action from a one fetch action to another. Not clear why this is important; should give some more context. -Writing Custom Actions,https://backstage.io/docs/features/software-templates/writing-custom-actions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to create a custom template action -Writing Custom Field Extensions,https://backstage.io/docs/features/software-templates/writing-custom-field-extensions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",More on customizing templates: creating your own field types -Writing custom step layouts,https://backstage.io/docs/features/software-templates/writing-custom-step-layouts,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Still more on customizing templates: creating your own step layouts -Authorizing parameters steps and actions,https://backstage.io/docs/features/software-templates/authorizing-parameters-steps-and-actions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Authorization in custom templates -Experimental: Testing out the alpha Scaffolder plugin,https://backstage.io/docs/features/software-templates/testing-scaffolder-alpha,task,administrator,"installation, setup, config",Release Notes,Information about features that are in flux or still in development should have their own documentation separate from the production system. The feature should be described in the Release Notes. -Migrating to v1beta3 templates,https://backstage.io/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3,,administrator,"installation, setup, config",Release Notes,Information about features that are in flux or still in development should have their own documentation separate from the production system. The feature should be described in the Release Notes. -Overview,https://backstage.io/docs/features/search/,concept,administrator; user,use,User Guide,"Intro to the search feature, including its configurability as a plugin" -Getting Started with Search,https://backstage.io/docs/features/search/getting-started,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Installing and configuring frontend and backend search -Search Concepts,https://backstage.io/docs/features/search/concepts,concept,administrator; user,"deployment, use",Technical Overview,Description of search system components. -Search Architecture,https://backstage.io/docs/features/search/architecture,concept,all,"decision, deployment",Architecture Overview,Description of search architecture -Search Engines,https://backstage.io/docs/features/search/search-engines,concept,administrator; user,deployment,Architecture Overview,Describes search backends available by default -How-To guides,https://backstage.io/docs/features/search/how-to-guides,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to deploy a custom search backend -Overview,https://backstage.io/docs/features/techdocs/,concept,all,"decision, deployment",Architecture Overview,Intro to tech docs feature -Getting Started,https://backstage.io/docs/features/techdocs/getting-started,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide",Install and config instructions for the TechDoc frontend and backend plugins -Concepts,https://backstage.io/docs/features/techdocs/concepts,concept,administrator; user,"deployment, use","Architecture Overview, Installation Guide",Describes the TechDocs plugin component architecture. -TechDocs Addons,https://backstage.io/docs/features/techdocs/addons,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Describes how to install and configure add-ons to the TechDocs plugin -TechDocs Architecture,https://backstage.io/docs/features/techdocs/architecture,concept,administrator; user,deployment,Architecture Overview,TechDocs architecture block diagrams. -Creating and Publishing Documentation,https://backstage.io/docs/features/techdocs/creating-and-publishing,task,user,use,User Guide,How to add existing docs or create a new doc in TechDcos -TechDocs Configuration Options,https://backstage.io/docs/features/techdocs/configuration,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",A description in an example YAML file of the TechDocs configuration parameters. Don’t know if it’s comprehensive or not. -Using Cloud Storage for TechDocs generated files,https://backstage.io/docs/features/techdocs/using-cloud-storage,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up TechDocs on major cloud services -Configuring CI/CD to generate and publish TechDocs sites,https://backstage.io/docs/features/techdocs/configuring-ci-cd,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to automate TechDocs publication in CI/CD -TechDocs CLI,https://backstage.io/docs/features/techdocs/cli,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Reference and how-to information on using the CLI. A bit of a catch-all; should be parceled out in more focused docs. -How-To guides,https://backstage.io/docs/features/techdocs/how-to-guides,task,administrator; user,"deployment, use",Recipe,How-tos for various TechDocs tasks. probably partly redundant with other pages. -Troubleshooting,https://backstage.io/docs/features/techdocs/troubleshooting,task,administrator; user,"deployment, use",Maintenance Guide; User Guide,How to solve several trouble scenarios -FAQ,https://backstage.io/docs/features/techdocs/faqs,concept,administrator; user,"deployment, use",KB,Info about the TechDocs plugin. Probably partly redundant with other pages. -Integrations,,,,,, -Overview,https://backstage.io/docs/integrations/,concept,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Intro to integrations. Needs to be expanded. There are about a dozen listed integrations with common cloud providers and software repos. This could be its own supplement to the installation guide or a chapter or appendix. It's almost certain to be needed for any major installation. -Plugins,,,,,, -Intro to plugins,https://backstage.io/docs/plugins/,concept,administrator,deployment,Architecture Overview,"This introduction needs to be expanded (though that material might exist elsewhere). There are pointers here mostly to contributor actions. ""Contributing a plugin"" needs to be its own separate document on the GitHub site." -Existing plugins,https://backstage.io/docs/plugins/existing-plugins,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",This is a pointer to the plugin catalog. The catalog should be an appendix to the installation and config guide. -Create a Backstage Plugin,https://backstage.io/docs/plugins/create-a-plugin,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",This is actually a brief description of how to install a plugin on an existing Backstage instance. -Plugin Development,https://backstage.io/docs/plugins/plugin-development,concept,"contributor, admin","contribute, maintenance",Contributor reference,A brief outline of how to develop a plugin. Should go in the contributor guide. -Structure of a Plugin,https://backstage.io/docs/plugins/structure-of-a-plugin,reference,"contributor, admin","contribute, maintenance",Contributor reference,Description of the structure of a plugin. -Integrate into the Software Catalog,https://backstage.io/docs/plugins/integrating-plugin-into-software-catalog,task,contributor,contribute,Contributor reference,"Describes how to add a plugin to the entities page on a Backstage instance. Described as ""advanced"" and ""experimental""." -Integrating Search into a plugin,https://backstage.io/docs/plugins/integrating-search-into-plugins,task,contributor,contribute,Contributor reference,Instructions for implementing search in a plugin. -Composability System,https://backstage.io/docs/plugins/composability,concept,contributor,contribute,Contributor reference,How plugins talk to each other using React extension. Contains some instructional code that should be separated into a procedure. -Customization (Experimental),https://backstage.io/docs/plugins/customization,task,"contributor, user","contribute, use","Contributor reference, User guide","How to customize a plugin. Instructions for both contributor (plugin developer) and a short snippet for a developer to use in an existing installation. Labeled ""experimental""." -Plugin Analytics,https://backstage.io/docs/plugins/analytics,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","Conceptual, reference, and (mostly) task information about using a supplied analytics API to collect usage data on Backstage." -Feature Flags,https://backstage.io/docs/plugins/feature-flags,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide","How to set features flags to define plugin behavior, both in plugin code and from the Backstage application." -Proxying,https://backstage.io/docs/plugins/proxying,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up an HTTP proxy to reach backend services from the Backstage frontend -Backend plugins,https://backstage.io/docs/plugins/backend-plugin,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Instructions for an admin to create and configure a backend plugin. This is one of those pieces of content that spans admin and contributor. -Call Existing API,https://backstage.io/docs/plugins/call-existing-api,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide",How to call an arbitrary API from the Backstage frontend -URL Reader,https://backstage.io/docs/plugins/url-reader,task,contributor,contribute,Contributor reference,How to use the Backstage URL reader API to securely read files from a plugin. -Testing with Jest,https://backstage.io/docs/plugins/testing,concept,contributor,contribute,Contributor reference,A description of the infrastructure (Jest) and principles to use when writing unit tests for plugins. -Publish private,https://backstage.io/docs/plugins/publish-private,,,,,"""TODO""" -Add to Marketplace,https://backstage.io/docs/plugins/add-to-marketplace,task,contributor,contribute,Contributor reference,How to add a plugin to the plugin library listed in the documentation -Observability,https://backstage.io/docs/plugins/observability,reference,contributor,contribute,Contributor reference,A brief overview of some logging mechanisms. Covered elsewhere. -Configuration,,,,,, -Static Configuration in Backstage,https://backstage.io/docs/conf/,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. -Reading Backstage Configuration,https://backstage.io/docs/conf/reading,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. -Writing Backstage Configuration Files,https://backstage.io/docs/conf/writing,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. -Defining Configuration for your Plugin,https://backstage.io/docs/conf/defining,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. -Auth and identity,,,,,, -Authentication in Backstage,https://backstage.io/docs/auth/,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","How to configure authentication. There are at least 14 individual pages for various providers giving detailed instructions for these providers: ""https://backstage.io/docs/auth/atlassian/provider"" and so on." -Sign-in Identities and Resolvers,https://backstage.io/docs/auth/identity-resolver,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up identities for authorization. Probably useful to plugin contributors as well. -OAuth and OpenID Connect,https://backstage.io/docs/auth/oauth,concept,"contributor, admin","contribute, maintenance","Contributor reference, User guide",Describes how tokens are used by Backstage for third-party services. Includes a sequence diagram. -OIDC provider from scratch,https://backstage.io/docs/auth/oidc,task,"contributor, admin",contribute,Contributor reference,How to use Open ID Connect (OIDC) to connect to Backstage. -Contributing New Providers,https://backstage.io/docs/auth/add-auth-provider,task,contributor,contribute,Contributor reference,How to add support for a new authentication provider. Recommended solely for contributors. -Service to Service Auth,https://backstage.io/docs/auth/service-to-service-auth,task,contributor,contribute,Contributor reference,How to set up a plugin to authenticate another service or plugin. -Troubleshooting Auth,https://backstage.io/docs/auth/troubleshooting,task,"contributor, admin",contribute,"Installation, Setup, and Config Guide",Troubleshooting various authentication problems. These span development of plugins to administration of Backstage instances. -Glossary,https://backstage.io/docs/auth/glossary,reference,all,any,,A glossary of terms for authentication. -Permissions,,,,,, -Overview,https://backstage.io/docs/permissions/overview,concept,all,deployment,Architecture Overview,"An introduction to authorization in Backstage, with a flow diagram." -Concepts,https://backstage.io/docs/permissions/concepts,reference,"contributor, admin","contribute, maintenance",Contributor reference,A glossary of authorization terms. -Getting Started,https://backstage.io/docs/permissions/getting-started,task,"contributor, admin","contribute, maintenance",Contributor reference,How to set up authorization in a Backstage plugin. -Writing a permission policy,https://backstage.io/docs/permissions/writing-a-policy,task,"contributor, admin","contribute, maintenance",Contributor reference,How to write a permission policy in a Typescript file. -Frontend Integration,https://backstage.io/docs/permissions/frontend-integration,task,"contributor, admin","contribute, maintenance",Contributor reference,An example showing what to do when frontend permission policy needs to be set. -Defining custom permission rules,https://backstage.io/docs/permissions/custom-rules,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up a custom rule outside the context of a plugin. -1. Tutorial setup,https://backstage.io/docs/permissions/plugin-authors/01-setup,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. -2. Adding a basic permission check,https://backstage.io/docs/permissions/plugin-authors/02-adding-a-basic-permission-check,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. -3. Adding a resource permission check,https://backstage.io/docs/permissions/plugin-authors/03-adding-a-resource-permission-check,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. -4. Authorizing access to paginated data,https://backstage.io/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. -5. Frontend Components with Authorization,https://backstage.io/docs/permissions/plugin-authors/05-frontend-authorization,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. -Deployment,,,,,, -Overview,https://backstage.io/docs/deployment/,concept,administrator,deployment,"Installation, Setup, and Config Guide",Introduction to deploying a Backstage instance. -Scaling,https://backstage.io/docs/deployment/scaling,concept,administrator,deployment,"Installation, Setup, and Config Guide",Brief discussion of how to scale Backstage across an org -Docker,https://backstage.io/docs/deployment/docker,task,administrator,deployment,"Installation, Setup, and Config Guide",How to deploy using Docker. -Kubernetes,https://backstage.io/docs/deployment/k8s,task,administrator,deployment,"Installation, Setup, and Config Guide",Fairly extensive instructions on how to deploy Backstage using Docker on Kubernetes -Heroku,https://backstage.io/docs/deployment/heroku,task,administrator,deployment,"Installation, Setup, and Config Guide",Deploying using Heroic -Koyeb,https://backstage.io/docs/deployment/koyeb,task,administrator,deployment,"Installation, Setup, and Config Guide",Deploying using Kobe -AWS Fargate via Flightcontrol,https://backstage.io/docs/deployment/flightcontrol,task,administrator,deployment,"Installation, Setup, and Config Guide",Deploying on AWS using Flightcontrol -Designing for Backstage,,,,,, -Design,https://backstage.io/docs/dls/design,concept,contributor,contribute,Contributor overview,Introduction to the Backstage OSS project. -Component Design Guidelines,https://backstage.io/docs/dls/component-design-guidelines,concept,contributor,contribute,Contributor reference,Visual design guidelines for components -Contributing to Storybook,https://backstage.io/docs/dls/contributing-to-storybook,task,contributor,contribute,Contributor reference,How to add a control to the Backstage Storybook catalog -Figma,https://backstage.io/docs/dls/figma,reference,contributor,contribute,Contributor reference,Link to the Figma component library for Backstage -API Reference,,,,,, -Utility APIs,https://backstage.io/docs/api/utility-apis,task,contributor,contribute,Contributor reference,Describes the infrastructure for creating and using APIs that operate between plugins. -Package Index,https://backstage.io/docs/reference/,reference,contributor,contribute,Contributor reference,A lengthy catalog of APIs -Deprecations,https://backstage.io/docs/api/deprecations,reference,all,any,,Describes deprecated elements in Backstage. Deprecations should be noted in reference material and described in release notes. -Tutorials,,,,,, -Future developer journey,https://backstage.io/docs/tutorials/journey,task,"contributor, admin",contribute,Recipe,"Extended example about a fictional developer adding a new plugin to an installation, then to the project" -Adding Custom Plugin to Existing Monorepo App,https://backstage.io/docs/tutorials/quickstart-app-plugin,task,administrator,deployment,Recipe,How to develop a plugin in an existing Backstage installation (app) -React Router 6.0 Migration,https://backstage.io/docs/tutorials/react-router-stable-migration,task,administrator,"installation, setup, config",Release Notes,"How to upgrade to a newer version of React router. A version-specific procedure that should be hidden from general admin procedures. Should have been a release-specific task, if necessary at all" -Package Role Migration,https://backstage.io/docs/tutorials/package-role-migration,task,administrator,"installation, setup, config",Release Notes,"Another transitional step that should be part of a version upgrade, not a user tutorial." -Migrating away from @backstage/core,https://backstage.io/docs/tutorials/migrating-away-from-core,task,administrator,"installation, setup, config",Release Notes,Another refactoring migration. Remove from tutorials. -Configuring Plugin Databases,https://backstage.io/docs/tutorials/configuring-plugin-databases,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","I could see putting this in a recipe guide or a config guide, plugin-specific or otherwise. Not a tutorial." -Switching Backstage from SQLite to PostgreSQL,https://backstage.io/docs/tutorials/switching-sqlite-postgres,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to change the default DB from SQLite to PostgreSQL. This should be in the basic configuration guide. -Using the Backstage Proxy from Within a Plugin,https://backstage.io/docs/tutorials/using-backstage-proxy-within-plugin,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to access an external API using a proxy. A plugin configuration task. -Migration to Yarn 3,https://backstage.io/docs/tutorials/yarn-migration,task,administrator,deployment,Release Notes,Another release-specific migration. Remove from tutorials. -Architecture Decision Records (ADRs),,,,,, -Overview,https://backstage.io/docs/architecture-decisions/,concept,"contributor, admin",deployment,Architecture Overview,"An intro to architectural decision records (ADRs). Potentially part of an architecture overview. Could be omitted from the user doc altogether, though. Primarily of interest to contributors." -ADR001: Architecture Decision Record (ADR) log,https://backstage.io/docs/architecture-decisions/adrs-adr001,concept,contributor,contribute,Contributor reference,Meta ADR about where to store ADRs. -ADR002: Default Software Catalog File Format,https://backstage.io/docs/architecture-decisions/adrs-adr002,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR003: Avoid Default Exports and Prefer Named Exports,https://backstage.io/docs/architecture-decisions/adrs-adr003,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR004: Module Export Structure,https://backstage.io/docs/architecture-decisions/adrs-adr004,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR005: Catalog Core Entities,https://backstage.io/docs/architecture-decisions/adrs-adr005,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR006: Avoid React.FC and React.SFC,https://backstage.io/docs/architecture-decisions/adrs-adr006,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR007: Use MSW to mock http requests,https://backstage.io/docs/architecture-decisions/adrs-adr007,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR008: Default Catalog File Name,https://backstage.io/docs/architecture-decisions/adrs-adr008,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR009: Entity References,https://backstage.io/docs/architecture-decisions/adrs-adr009,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR010: Use the Luxon Date Library,https://backstage.io/docs/architecture-decisions/adrs-adr010,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR011: Plugin Package Structure,https://backstage.io/docs/architecture-decisions/adrs-adr011,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR012: Use Luxon.toLocaleString and date/time presets,https://backstage.io/docs/architecture-decisions/adrs-adr012,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -ADR013: Proper use of HTTP fetching libraries,https://backstage.io/docs/architecture-decisions/adrs-adr013,concept,contributor,contribute,Contributor reference,Information about a particular design decision. -FAQ,,,,,, -FAQ,https://backstage.io/docs/FAQ,reference,all,any,KB,"This is a fairly robust FAQ. I usually recommend doing away with a FAQ on the grounds that it's a last resort for someone looking for information. Distribute its topics to where they belong in the documentation. Use a knowledge base (similar, but longer-format articles with conceptual information only) for miscellaneous, indexed, conceptual information." -Experimental Backend System,,,,,, -Introduction,https://backstage.io/docs/backend-system/,concept,"contributor, admin",deployment,Contributor reference,"Information about a refactoring of existing functionality should be kept in the developer (contributor) discussion until it is deployed, at which point it should be documented in the release notes. Mentions of timing (""this component is in alpha""; ""currently this works like this""; ""we plan to ..."") should be avoided entirely in the product regular documentation. Version-specific information should be documented at the time of release in the release notes. If the change affects functionality, the new functionality should replace the old in the documentation set starting at the new version of the doc." -Overview,https://backstage.io/docs/backend-system/architecture/index,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" -Services,https://backstage.io/docs/backend-system/architecture/services,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" -Plugins,https://backstage.io/docs/backend-system/architecture/plugins,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" -Extension Points,https://backstage.io/docs/backend-system/architecture/extension-points,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" -Modules,https://backstage.io/docs/backend-system/architecture/modules,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" -Naming Patterns,https://backstage.io/docs/backend-system/architecture/naming-patterns,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" -Accessibility,,,,,, -Backstage Accessibility,https://backstage.io/docs/accessibility/,task,contributor,contribute,Contributor reference,How to incorporate accessibility into contributed software components +Title,URL,Doc Type,User Role,Use Case,Doc Suite Position,Comment +Overview,,,,,, +What is Backstage?,https://backstage.io/docs/overview/what-is-backstage,concept,adopter,decision,Technical Overview,Introductory +Architecture overview,https://backstage.io/docs/overview/architecture-overview,concept,administrator,deployment,Architecture Overview,"Substantial, in-depth view of architecture" +Roadmap,https://backstage.io/docs/overview/roadmap,concept,administrator,"deployment, maintenance",Release Notes,Should be updated frequently; move to release notes +Vision,https://backstage.io/docs/overview/vision,concept,"contributor, adopter","strategy, sales",White Paper,"Short, high-level statement of vision." +The Spotify Story,https://backstage.io/docs/overview/background,concept,"contributor, adopter","strategy, sales",White Paper,Background info. Move to website. +Strategies for adopting,https://backstage.io/docs/overview/adopting,concept,adopter,decision,Overview,"Would be useful in adoption go/no-go decisions, and in adoption/deployment/configuration." +Release and Versioning Policy,https://backstage.io/docs/overview/versioning-policy,concept,"contributor, adopter","contribute, maintenance","Release Notes, Contributor Instructions", +Backstage Threat Model,https://backstage.io/docs/overview/threat-model,concept,administrator,deployment,"Architecture Overview, Installation Guide",Required by admin to set up security posture +Support and community,https://backstage.io/docs/overview/support,reference,any,"support, decision, contrib","RN, FAQ, KB, Overviews",Should be available to any interested user from almost anywhere +Backstage Glossary,https://backstage.io/docs/overview/glossary,reference,any,any,KB,"Should be available generally, esp. to new users" +Logo assets,https://backstage.io/docs/overview/logos,reference,"contributor, adopter",contribute,,Reference info for contributing designer +Getting Started,,,,,, +Getting Started,https://backstage.io/docs/getting-started/,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Installation instructions +Getting Started configuring Backstage,https://backstage.io/docs/getting-started/configuration,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide; Getting Started Guide","Split: Configuring database, authentication (installation); Creating your first components (getting started)" +Create an App,https://backstage.io/docs/getting-started/create-an-app,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","How to set up an instance. Might need two setup procedures, one for users and one for admins." +Configuring App with plugins,https://backstage.io/docs/getting-started/configure-app-with-plugins,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Should go in a chapter of the install guide devoted to installing existing plugins +Customize the look-and-feel of your App,https://backstage.io/docs/getting-started/app-custom-theme,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Should be a chapter of the install guide +Backstage homepage - Setup and Customization,https://backstage.io/docs/getting-started/homepage,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide", +Keeping Backstage Updated,https://backstage.io/docs/getting-started/keeping-backstage-updated,task,administrator,"installation, setup, config",IS&C; RN,Upgrade procedures in admin guide; particular upgrades in release notes +Key Concepts,https://backstage.io/docs/getting-started/concepts,reference,administrator,,,This is a list of software dependencies. Needed by admin. Upgrades needed by each release in RN. +Contributors,https://backstage.io/docs/getting-started/contributors,task,contributor,contribute,Contributor setup guide,"Contributor guide can be limited to GitHub, or a separate contributor guide put on the website" +Getting Involved,https://backstage.io/docs/getting-started/getting-involved,reference,contributor,contribute,Contributor overview,This material belongs in the intro to a contributor guide +Backstage Project Structure,https://backstage.io/docs/getting-started/project-structure,reference,contributor,contribute,Contributor reference,"Structure of the GitHub repo, annotated. Reference for contributors." +Local Development,,,,,, +Overview,https://backstage.io/docs/local-dev/cli-overview,concept,administrator,deployment,Architecture Overview,"This is part of the architecture overview, a discussion of the components of the CLI" +Build System,https://backstage.io/docs/local-dev/cli-build-system,concept,administrator,deployment,Architecture Overview,Description of how the Build system works; belongs in the Architecture Overview +Commands,https://backstage.io/docs/local-dev/cli-commands,reference,administrator; user,use,API Reference,"This is a command reference for the CLI, which seems to be a tool for doing builds of components in Backstage" +Linking in Local Packages,https://backstage.io/docs/local-dev/linking-local-packages,task,user,use,Recipe,This is a technique for testing a build. Goes in a recipe book or use and testing guide. +Debugging Backstage,https://backstage.io/docs/local-dev/debugging,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Description of how to change the logging level in Backstage. +Core Features,,,,,, +Overview,https://backstage.io/docs/features/software-catalog/,task,user,use,User Guide,Basic catalog tasks. Also a short intro to the catalog (conceptual). +The Life of an Entity,https://backstage.io/docs/features/software-catalog/life-of-an-entity,concept,administrator; user,deployment,Architecture Overview,Detailed description of data ingestion when importing an entity. +Catalog Configuration,https://backstage.io/docs/features/software-catalog/configuration,concept,administrator; user,deployment,Architecture Overview,Additional information for ingesting entities +System Model,https://backstage.io/docs/features/software-catalog/system-model,concept,user,use,User Guide,Describes the model behind various entities. Some of this could go in the Knowledge Base as well maybe. +YAML File Format,https://backstage.io/docs/features/software-catalog/descriptor-format,reference,user,use,User Guide,"Reference to entity descriptors, with examples in JSON." +Entity References,https://backstage.io/docs/features/software-catalog/references,reference,user,use,User Guide,Description of how entities reference other entities +Well-known Annotations,https://backstage.io/docs/features/software-catalog/well-known-annotations,reference,user,use,User Guide,More on entities +Well-known Relations,https://backstage.io/docs/features/software-catalog/well-known-relations,reference,user,use,User Guide,More on entities +Well-known Statuses,https://backstage.io/docs/features/software-catalog/well-known-statuses,reference,user,use,User Guide,More on entities +Extending the model,https://backstage.io/docs/features/software-catalog/extending-the-model,reference,user,use,User Guide,More on entities +External integrations,https://backstage.io/docs/features/software-catalog/external-integrations,reference,user,use,User Guide,More on entities +Catalog Customization,https://backstage.io/docs/features/software-catalog/catalog-customization,task,administrator,deployment,"Installation, Setup, and Config Guide",How to customize the entity display page. A recipe for the site admin +API,https://backstage.io/docs/features/software-catalog/software-catalog-api,reference,administrator; user,use,API Reference,The Entity API. Could be teased apart into a true reference and a set of recipes. +Creating the Catalog Graph,https://backstage.io/docs/features/software-catalog/creating-the-catalog-graph,reference,user,use,User Guide,Describes the catalog model and what is displayed in the UI +Overview,https://backstage.io/docs/features/kubernetes/,concept,user,use,Kubernetes plugin guide,Intro to the 2 Kubernetes plugins +Installation,https://backstage.io/docs/features/kubernetes/installation,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Could go in the main install guide or in a separate k8s guide +Configuration,https://backstage.io/docs/features/kubernetes/configuration,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide","Continuation of k8s install instructions, but contains mostly descriptions of the config settings" +Kubernetes Authentication,https://backstage.io/docs/features/kubernetes/authentication,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Describes how to authenticate k8s on various services. +Troubleshooting,https://backstage.io/docs/features/kubernetes/troubleshooting,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",What to do if k8s doesn’t show up as a service entity +Proxy,https://backstage.io/docs/features/kubernetes/proxy,task,"contributor, admin","installation, setup, config","Installation, Setup, and Config Guide",How to set up a k8s proxy endpoint. Known limitation should be moved to a release note. +Overview,https://backstage.io/docs/features/software-templates/,task,administrator; user,getting started,Getting Started Guide (“Hello World”),“Disable Register Existing Component button” is an admin task that should be in the config documentation +Configuration,https://backstage.io/docs/features/software-templates/configuration,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to configure a template +Adding your own Templates,https://backstage.io/docs/features/software-templates/adding-templates,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to add a template +Writing Templates,https://backstage.io/docs/features/software-templates/writing-templates,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",The anatomy of a template and how to write one. +Input Examples,https://backstage.io/docs/features/software-templates/input-examples,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Anatomy of template input components. Could be a mini-cookbook or a section of the config instructions for Templates +Builtin actions,https://backstage.io/docs/features/software-templates/builtin-actions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Describes how to migrate a fetch action from a one fetch action to another. Not clear why this is important; should give some more context. +Writing Custom Actions,https://backstage.io/docs/features/software-templates/writing-custom-actions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to create a custom template action +Writing Custom Field Extensions,https://backstage.io/docs/features/software-templates/writing-custom-field-extensions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",More on customizing templates: creating your own field types +Writing custom step layouts,https://backstage.io/docs/features/software-templates/writing-custom-step-layouts,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Still more on customizing templates: creating your own step layouts +Authorizing parameters steps and actions,https://backstage.io/docs/features/software-templates/authorizing-parameters-steps-and-actions,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Authorization in custom templates +Experimental: Testing out the alpha Scaffolder plugin,https://backstage.io/docs/features/software-templates/testing-scaffolder-alpha,task,administrator,"installation, setup, config",Release Notes,Information about features that are in flux or still in development should have their own documentation separate from the production system. The feature should be described in the Release Notes. +Migrating to v1beta3 templates,https://backstage.io/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3,,administrator,"installation, setup, config",Release Notes,Information about features that are in flux or still in development should have their own documentation separate from the production system. The feature should be described in the Release Notes. +Overview,https://backstage.io/docs/features/search/,concept,administrator; user,use,User Guide,"Intro to the search feature, including its configurability as a plugin" +Getting Started with Search,https://backstage.io/docs/features/search/getting-started,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Installing and configuring frontend and backend search +Search Concepts,https://backstage.io/docs/features/search/concepts,concept,administrator; user,"deployment, use",Technical Overview,Description of search system components. +Search Architecture,https://backstage.io/docs/features/search/architecture,concept,all,"decision, deployment",Architecture Overview,Description of search architecture +Search Engines,https://backstage.io/docs/features/search/search-engines,concept,administrator; user,deployment,Architecture Overview,Describes search backends available by default +How-To guides,https://backstage.io/docs/features/search/how-to-guides,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to deploy a custom search backend +Overview,https://backstage.io/docs/features/techdocs/,concept,all,"decision, deployment",Architecture Overview,Intro to tech docs feature +Getting Started,https://backstage.io/docs/features/techdocs/getting-started,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide",Install and config instructions for the TechDoc frontend and backend plugins +Concepts,https://backstage.io/docs/features/techdocs/concepts,concept,administrator; user,"deployment, use","Architecture Overview, Installation Guide",Describes the TechDocs plugin component architecture. +TechDocs Addons,https://backstage.io/docs/features/techdocs/addons,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Describes how to install and configure add-ons to the TechDocs plugin +TechDocs Architecture,https://backstage.io/docs/features/techdocs/architecture,concept,administrator; user,deployment,Architecture Overview,TechDocs architecture block diagrams. +Creating and Publishing Documentation,https://backstage.io/docs/features/techdocs/creating-and-publishing,task,user,use,User Guide,How to add existing docs or create a new doc in TechDcos +TechDocs Configuration Options,https://backstage.io/docs/features/techdocs/configuration,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",A description in an example YAML file of the TechDocs configuration parameters. Don’t know if it’s comprehensive or not. +Using Cloud Storage for TechDocs generated files,https://backstage.io/docs/features/techdocs/using-cloud-storage,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up TechDocs on major cloud services +Configuring CI/CD to generate and publish TechDocs sites,https://backstage.io/docs/features/techdocs/configuring-ci-cd,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to automate TechDocs publication in CI/CD +TechDocs CLI,https://backstage.io/docs/features/techdocs/cli,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Reference and how-to information on using the CLI. A bit of a catch-all; should be parceled out in more focused docs. +How-To guides,https://backstage.io/docs/features/techdocs/how-to-guides,task,administrator; user,"deployment, use",Recipe,How-tos for various TechDocs tasks. probably partly redundant with other pages. +Troubleshooting,https://backstage.io/docs/features/techdocs/troubleshooting,task,administrator; user,"deployment, use",Maintenance Guide; User Guide,How to solve several trouble scenarios +FAQ,https://backstage.io/docs/features/techdocs/faqs,concept,administrator; user,"deployment, use",KB,Info about the TechDocs plugin. Probably partly redundant with other pages. +Integrations,,,,,, +Overview,https://backstage.io/docs/integrations/,concept,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Intro to integrations. Needs to be expanded. There are about a dozen listed integrations with common cloud providers and software repos. This could be its own supplement to the installation guide or a chapter or appendix. It's almost certain to be needed for any major installation. +Plugins,,,,,, +Intro to plugins,https://backstage.io/docs/plugins/,concept,administrator,deployment,Architecture Overview,"This introduction needs to be expanded (though that material might exist elsewhere). There are pointers here mostly to contributor actions. ""Contributing a plugin"" needs to be its own separate document on the GitHub site." +Existing plugins,https://backstage.io/docs/plugins/existing-plugins,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",This is a pointer to the plugin catalog. The catalog should be an appendix to the installation and config guide. +Create a Backstage Plugin,https://backstage.io/docs/plugins/create-a-plugin,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",This is actually a brief description of how to install a plugin on an existing Backstage instance. +Plugin Development,https://backstage.io/docs/plugins/plugin-development,concept,"contributor, admin","contribute, maintenance",Contributor reference,A brief outline of how to develop a plugin. Should go in the contributor guide. +Structure of a Plugin,https://backstage.io/docs/plugins/structure-of-a-plugin,reference,"contributor, admin","contribute, maintenance",Contributor reference,Description of the structure of a plugin. +Integrate into the Software Catalog,https://backstage.io/docs/plugins/integrating-plugin-into-software-catalog,task,contributor,contribute,Contributor reference,"Describes how to add a plugin to the entities page on a Backstage instance. Described as ""advanced"" and ""experimental""." +Integrating Search into a plugin,https://backstage.io/docs/plugins/integrating-search-into-plugins,task,contributor,contribute,Contributor reference,Instructions for implementing search in a plugin. +Composability System,https://backstage.io/docs/plugins/composability,concept,contributor,contribute,Contributor reference,How plugins talk to each other using React extension. Contains some instructional code that should be separated into a procedure. +Customization (Experimental),https://backstage.io/docs/plugins/customization,task,"contributor, user","contribute, use","Contributor reference, User guide","How to customize a plugin. Instructions for both contributor (plugin developer) and a short snippet for a developer to use in an existing installation. Labeled ""experimental""." +Plugin Analytics,https://backstage.io/docs/plugins/analytics,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","Conceptual, reference, and (mostly) task information about using a supplied analytics API to collect usage data on Backstage." +Feature Flags,https://backstage.io/docs/plugins/feature-flags,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide","How to set features flags to define plugin behavior, both in plugin code and from the Backstage application." +Proxying,https://backstage.io/docs/plugins/proxying,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up an HTTP proxy to reach backend services from the Backstage frontend +Backend plugins,https://backstage.io/docs/plugins/backend-plugin,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",Instructions for an admin to create and configure a backend plugin. This is one of those pieces of content that spans admin and contributor. +Call Existing API,https://backstage.io/docs/plugins/call-existing-api,task,administrator; user,"installation, setup, config","Installation, Setup, and Config Guide",How to call an arbitrary API from the Backstage frontend +URL Reader,https://backstage.io/docs/plugins/url-reader,task,contributor,contribute,Contributor reference,How to use the Backstage URL reader API to securely read files from a plugin. +Testing with Jest,https://backstage.io/docs/plugins/testing,concept,contributor,contribute,Contributor reference,A description of the infrastructure (Jest) and principles to use when writing unit tests for plugins. +Publish private,https://backstage.io/docs/plugins/publish-private,,,,,"""TODO""" +Add to Marketplace,https://backstage.io/docs/plugins/add-to-marketplace,task,contributor,contribute,Contributor reference,How to add a plugin to the plugin library listed in the documentation +Observability,https://backstage.io/docs/plugins/observability,reference,contributor,contribute,Contributor reference,A brief overview of some logging mechanisms. Covered elsewhere. +Configuration,,,,,, +Static Configuration in Backstage,https://backstage.io/docs/conf/,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. +Reading Backstage Configuration,https://backstage.io/docs/conf/reading,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. +Writing Backstage Configuration Files,https://backstage.io/docs/conf/writing,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. +Defining Configuration for your Plugin,https://backstage.io/docs/conf/defining,reference,contributor,"contribute, maintenance",Contributor reference,These sections describe the static configuration files for plugins and how they're combined into the configuration for a Backstage implementation. +Auth and identity,,,,,, +Authentication in Backstage,https://backstage.io/docs/auth/,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","How to configure authentication. There are at least 14 individual pages for various providers giving detailed instructions for these providers: ""https://backstage.io/docs/auth/atlassian/provider"" and so on." +Sign-in Identities and Resolvers,https://backstage.io/docs/auth/identity-resolver,reference,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up identities for authorization. Probably useful to plugin contributors as well. +OAuth and OpenID Connect,https://backstage.io/docs/auth/oauth,concept,"contributor, admin","contribute, maintenance","Contributor reference, User guide",Describes how tokens are used by Backstage for third-party services. Includes a sequence diagram. +OIDC provider from scratch,https://backstage.io/docs/auth/oidc,task,"contributor, admin",contribute,Contributor reference,How to use Open ID Connect (OIDC) to connect to Backstage. +Contributing New Providers,https://backstage.io/docs/auth/add-auth-provider,task,contributor,contribute,Contributor reference,How to add support for a new authentication provider. Recommended solely for contributors. +Service to Service Auth,https://backstage.io/docs/auth/service-to-service-auth,task,contributor,contribute,Contributor reference,How to set up a plugin to authenticate another service or plugin. +Troubleshooting Auth,https://backstage.io/docs/auth/troubleshooting,task,"contributor, admin",contribute,"Installation, Setup, and Config Guide",Troubleshooting various authentication problems. These span development of plugins to administration of Backstage instances. +Glossary,https://backstage.io/docs/auth/glossary,reference,all,any,,A glossary of terms for authentication. +Permissions,,,,,, +Overview,https://backstage.io/docs/permissions/overview,concept,all,deployment,Architecture Overview,"An introduction to authorization in Backstage, with a flow diagram." +Concepts,https://backstage.io/docs/permissions/concepts,reference,"contributor, admin","contribute, maintenance",Contributor reference,A glossary of authorization terms. +Getting Started,https://backstage.io/docs/permissions/getting-started,task,"contributor, admin","contribute, maintenance",Contributor reference,How to set up authorization in a Backstage plugin. +Writing a permission policy,https://backstage.io/docs/permissions/writing-a-policy,task,"contributor, admin","contribute, maintenance",Contributor reference,How to write a permission policy in a Typescript file. +Frontend Integration,https://backstage.io/docs/permissions/frontend-integration,task,"contributor, admin","contribute, maintenance",Contributor reference,An example showing what to do when frontend permission policy needs to be set. +Defining custom permission rules,https://backstage.io/docs/permissions/custom-rules,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to set up a custom rule outside the context of a plugin. +1. Tutorial setup,https://backstage.io/docs/permissions/plugin-authors/01-setup,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. +2. Adding a basic permission check,https://backstage.io/docs/permissions/plugin-authors/02-adding-a-basic-permission-check,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. +3. Adding a resource permission check,https://backstage.io/docs/permissions/plugin-authors/03-adding-a-resource-permission-check,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. +4. Authorizing access to paginated data,https://backstage.io/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. +5. Frontend Components with Authorization,https://backstage.io/docs/permissions/plugin-authors/05-frontend-authorization,task,contributor,contribute,Contributor reference,Tutorial on setting up authorization for a plugin. +Deployment,,,,,, +Overview,https://backstage.io/docs/deployment/,concept,administrator,deployment,"Installation, Setup, and Config Guide",Introduction to deploying a Backstage instance. +Scaling,https://backstage.io/docs/deployment/scaling,concept,administrator,deployment,"Installation, Setup, and Config Guide",Brief discussion of how to scale Backstage across an org +Docker,https://backstage.io/docs/deployment/docker,task,administrator,deployment,"Installation, Setup, and Config Guide",How to deploy using Docker. +Kubernetes,https://backstage.io/docs/deployment/k8s,task,administrator,deployment,"Installation, Setup, and Config Guide",Fairly extensive instructions on how to deploy Backstage using Docker on Kubernetes +Heroku,https://backstage.io/docs/deployment/heroku,task,administrator,deployment,"Installation, Setup, and Config Guide",Deploying using Heroic +Koyeb,https://backstage.io/docs/deployment/koyeb,task,administrator,deployment,"Installation, Setup, and Config Guide",Deploying using Kobe +AWS Fargate via Flightcontrol,https://backstage.io/docs/deployment/flightcontrol,task,administrator,deployment,"Installation, Setup, and Config Guide",Deploying on AWS using Flightcontrol +Designing for Backstage,,,,,, +Design,https://backstage.io/docs/dls/design,concept,contributor,contribute,Contributor overview,Introduction to the Backstage OSS project. +Component Design Guidelines,https://backstage.io/docs/dls/component-design-guidelines,concept,contributor,contribute,Contributor reference,Visual design guidelines for components +Contributing to Storybook,https://backstage.io/docs/dls/contributing-to-storybook,task,contributor,contribute,Contributor reference,How to add a control to the Backstage Storybook catalog +Figma,https://backstage.io/docs/dls/figma,reference,contributor,contribute,Contributor reference,Link to the Figma component library for Backstage +API Reference,,,,,, +Utility APIs,https://backstage.io/docs/api/utility-apis,task,contributor,contribute,Contributor reference,Describes the infrastructure for creating and using APIs that operate between plugins. +Package Index,https://backstage.io/docs/reference/,reference,contributor,contribute,Contributor reference,A lengthy catalog of APIs +Deprecations,https://backstage.io/docs/api/deprecations,reference,all,any,,Describes deprecated elements in Backstage. Deprecations should be noted in reference material and described in release notes. +Tutorials,,,,,, +Future developer journey,https://backstage.io/docs/tutorials/journey,task,"contributor, admin",contribute,Recipe,"Extended example about a fictional developer adding a new plugin to an installation, then to the project" +Adding Custom Plugin to Existing Monorepo App,https://backstage.io/docs/tutorials/quickstart-app-plugin,task,administrator,deployment,Recipe,How to develop a plugin in an existing Backstage installation (app) +React Router 6.0 Migration,https://backstage.io/docs/tutorials/react-router-stable-migration,task,administrator,"installation, setup, config",Release Notes,"How to upgrade to a newer version of React router. A version-specific procedure that should be hidden from general admin procedures. Should have been a release-specific task, if necessary at all" +Package Role Migration,https://backstage.io/docs/tutorials/package-role-migration,task,administrator,"installation, setup, config",Release Notes,"Another transitional step that should be part of a version upgrade, not a user tutorial." +Migrating away from @backstage/core,https://backstage.io/docs/tutorials/migrating-away-from-core,task,administrator,"installation, setup, config",Release Notes,Another refactoring migration. Remove from tutorials. +Configuring Plugin Databases,https://backstage.io/docs/tutorials/configuring-plugin-databases,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide","I could see putting this in a recipe guide or a config guide, plugin-specific or otherwise. Not a tutorial." +Switching Backstage from SQLite to PostgreSQL,https://backstage.io/docs/tutorials/switching-sqlite-postgres,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to change the default DB from SQLite to PostgreSQL. This should be in the basic configuration guide. +Using the Backstage Proxy from Within a Plugin,https://backstage.io/docs/tutorials/using-backstage-proxy-within-plugin,task,administrator,"installation, setup, config","Installation, Setup, and Config Guide",How to access an external API using a proxy. A plugin configuration task. +Migration to Yarn 3,https://backstage.io/docs/tutorials/yarn-migration,task,administrator,deployment,Release Notes,Another release-specific migration. Remove from tutorials. +Architecture Decision Records (ADRs),,,,,, +Overview,https://backstage.io/docs/architecture-decisions/,concept,"contributor, admin",deployment,Architecture Overview,"An intro to architectural decision records (ADRs). Potentially part of an architecture overview. Could be omitted from the user doc altogether, though. Primarily of interest to contributors." +ADR001: Architecture Decision Record (ADR) log,https://backstage.io/docs/architecture-decisions/adrs-adr001,concept,contributor,contribute,Contributor reference,Meta ADR about where to store ADRs. +ADR002: Default Software Catalog File Format,https://backstage.io/docs/architecture-decisions/adrs-adr002,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR003: Avoid Default Exports and Prefer Named Exports,https://backstage.io/docs/architecture-decisions/adrs-adr003,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR004: Module Export Structure,https://backstage.io/docs/architecture-decisions/adrs-adr004,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR005: Catalog Core Entities,https://backstage.io/docs/architecture-decisions/adrs-adr005,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR006: Avoid React.FC and React.SFC,https://backstage.io/docs/architecture-decisions/adrs-adr006,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR007: Use MSW to mock http requests,https://backstage.io/docs/architecture-decisions/adrs-adr007,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR008: Default Catalog File Name,https://backstage.io/docs/architecture-decisions/adrs-adr008,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR009: Entity References,https://backstage.io/docs/architecture-decisions/adrs-adr009,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR010: Use the Luxon Date Library,https://backstage.io/docs/architecture-decisions/adrs-adr010,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR011: Plugin Package Structure,https://backstage.io/docs/architecture-decisions/adrs-adr011,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR012: Use Luxon.toLocaleString and date/time presets,https://backstage.io/docs/architecture-decisions/adrs-adr012,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +ADR013: Proper use of HTTP fetching libraries,https://backstage.io/docs/architecture-decisions/adrs-adr013,concept,contributor,contribute,Contributor reference,Information about a particular design decision. +FAQ,,,,,, +FAQ,https://backstage.io/docs/FAQ,reference,all,any,KB,"This is a fairly robust FAQ. I usually recommend doing away with a FAQ on the grounds that it's a last resort for someone looking for information. Distribute its topics to where they belong in the documentation. Use a knowledge base (similar, but longer-format articles with conceptual information only) for miscellaneous, indexed, conceptual information." +Experimental Backend System,,,,,, +Introduction,https://backstage.io/docs/backend-system/,concept,"contributor, admin",deployment,Contributor reference,"Information about a refactoring of existing functionality should be kept in the developer (contributor) discussion until it is deployed, at which point it should be documented in the release notes. Mentions of timing (""this component is in alpha""; ""currently this works like this""; ""we plan to ..."") should be avoided entirely in the product regular documentation. Version-specific information should be documented at the time of release in the release notes. If the change affects functionality, the new functionality should replace the old in the documentation set starting at the new version of the doc." +Overview,https://backstage.io/docs/backend-system/architecture/index,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" +Services,https://backstage.io/docs/backend-system/architecture/services,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" +Plugins,https://backstage.io/docs/backend-system/architecture/plugins,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" +Extension Points,https://backstage.io/docs/backend-system/architecture/extension-points,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" +Modules,https://backstage.io/docs/backend-system/architecture/modules,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" +Naming Patterns,https://backstage.io/docs/backend-system/architecture/naming-patterns,concept,"contributor, admin",deployment,Contributor reference,"See notes on the ""Backend System"" intro, https://backstage.io/docs/backend-system/" +Accessibility,,,,,, +Backstage Accessibility,https://backstage.io/docs/accessibility/,task,contributor,contribute,Contributor reference,How to incorporate accessibility into contributed software components \ No newline at end of file From 5f769ae5296ee8d5ed2495d8b710b38076e57720 Mon Sep 17 00:00:00 2001 From: Nate W Date: Mon, 27 May 2024 18:15:56 -0700 Subject: [PATCH 09/10] correcting links, reformatting tables, other formatting corrections Signed-off-by: Nate W Signed-off-by: Patrice Chalin --- README.md | 14 ++-- assessments/README.md | 4 +- docs/analysis/criteria.md | 6 +- docs/analysis/howto.md | 4 +- docs/analysis/resources/README.md | 4 +- docs/analysis/resources/analysis-template.md | 78 ++++++++++---------- 6 files changed, 55 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 13b69d0..fc1f3b7 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,11 @@ This repository holds resources provided by the CNCF Technical Documentation tea The full-time staff of the CNCF Tech Docs team is: -GitHub ID | Role ----|--- -[@chalin](https://github.com/chalin) | Senior technical writer -[@nate-double-u](https://github.com/nate-double-u) | Developer advocate & technical writer -[@thisisobate](https://github.com/thisisobate) | Developer advocate +| GitHub ID | Role | +|----------------------------------------------------|---------------------------------------| +| [@chalin](https://github.com/chalin) | Senior technical writer | +| [@nate-double-u](https://github.com/nate-double-u) | Developer advocate & technical writer | +| [@thisisobate](https://github.com/thisisobate) | Developer advocate | @@ -23,7 +23,7 @@ Various consultants and volunteers also contribute to CNCF Tech Docs projects. The CNCF tech docs team holds office hours on the [fourth Wednesday of every month at 8am Pacific time](https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours). -Office hours started on 30 September, 2020. +Office hours started on 30 September 2020. ### Meeting link @@ -37,7 +37,7 @@ We store ongoing meeting notes in a [Google doc](https://docs.google.com/documen The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance-program][]. -[assistance-program]: ./techdoc-assistance.md +[assistance-program]: ./assistance.md ### Resources diff --git a/assessments/README.md b/assessments/README.md index 99d212e..84034f2 100644 --- a/assessments/README.md +++ b/assessments/README.md @@ -4,9 +4,9 @@ The goals of a CNCF technical documentation analysis are to: -- Examine the current project technical documentation and website against the CNCF's analysis framework, as described in the doc analysis [criteria](./criteria.md). +- Examine the current project technical documentation and website against the CNCF's analysis framework, as described in the doc analysis [criteria](../docs/analysis/criteria.md). - Compare the documentation against the current or proposed maturity level for the overall project. -- Recommends a program of key improvements with the largest return on investment. These improvements are documented as *recommendations* in the analysis document and expanded in a companion [implementation plan](./implementation-template.md) and [issues backlog](./umbrella-issue-template.md). +- Recommends a program of key improvements with the largest return on investment. These improvements are documented as *recommendations* in the analysis document and expanded in a companion [implementation plan](../docs/analysis/resources/implementation-template.md) and [issues backlog](../docs/analysis/resources/umbrella-issue-template.md). ## Audience diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index 138ad68..258783b 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -161,7 +161,7 @@ maturity levels so, for example, incubating projects must satisfy the requirements for sandbox projects. - **Sandbox** - - [Website guidelines](../docs/website-guidelines-checklist.md): majority of the guidelines are satisfied + - [Website guidelines](../../docs/website-guidelines-checklist.md): majority of the guidelines are satisfied - [Docs assessment][]: consider [submitting a request][service desk] for an assessment as early as possible to avoid documentation and website rework. - **Project documentation** may or may not be present -- it is acceptable at @@ -190,11 +190,11 @@ requirements for sandbox projects. documentation. [archived state]: https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories -[docs assessment]: /assessments/howto.md +[docs assessment]: ./howto.md [maturity level]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations [service desk]: https://servicedesk.cncf.io [single-source requirement]: #single-source-requirement -[website guidelines]: /howto/website-guidelines-checklist.md +[website guidelines]: ../website-guidelines-checklist.md ### Usability, accessibility and devices diff --git a/docs/analysis/howto.md b/docs/analysis/howto.md index f4c56d9..fd34556 100644 --- a/docs/analysis/howto.md +++ b/docs/analysis/howto.md @@ -11,14 +11,14 @@ The goals of a CNCF technical documentation analysis are to: - Examine the current project technical documentation and website against the CNCF's analysis framework, as described in the doc analysis [criteria](./criteria.md). - Compare the documentation against the current or proposed maturity level for the overall project. -- Recommends a program of key improvements with the largest return on investment. These improvements are documented as *recommendations* in the analysis document and expanded in a companion [implementation plan](./implementation-template.md) and [issues backlog](./umbrella-issue-template.md). +- Recommends a program of key improvements with the largest return on investment. These improvements are documented as *recommendations* in the analysis document and expanded in a companion [implementation plan](./resources/implementation-template.md) and [issues backlog](./resources/umbrella-issue-template.md). ## Doing a Tech Docs Analysis The tech docs analysis consists of some repository bookkeeping (Prerequisites), then of three overall tasks: -1. Write the analysis document: Evaluate the existing project documentation with respect to the project maturity level (or proposed maturity level, if the analysis is associated with an upgrade reqeust). Identify gaps with CNCF criteria. Write general recommendations to close the largest and most important gaps. +1. Write the analysis document: Evaluate the existing project documentation with respect to the project maturity level (or proposed maturity level, if the analysis is associated with an upgrade request). Identify gaps with CNCF criteria. Write general recommendations to close the largest and most important gaps. 2. Write the implementation plan: Decompose the recommendations to specific improvement suggestions. These can be additions or revisions to the docs; reorganization; website infrastructure changes; or any other work that will close the gaps. Make suggestions specific (if you propose reorganizing a section, for example, provide an outline) but provide enough information that a contributor could solve the problem differently if they have a different idea (make it clear that your proposed outline is only one possible reorganization, e.g.). 3. Write the issue backlog. diff --git a/docs/analysis/resources/README.md b/docs/analysis/resources/README.md index cd9f414..6d1e728 100644 --- a/docs/analysis/resources/README.md +++ b/docs/analysis/resources/README.md @@ -11,5 +11,5 @@ Use the templates in this directory to perform a documentation analysis for CNCF Resources for completing a documentation analysis, including a [how-to][] guide and analysis [criteria][], are in the `docs` directory. -[how-to]: ../docs/howto.md -[criteria]: ../docs/criteria.md \ No newline at end of file +[how-to]: ../howto.md +[criteria]: ../criteria.md \ No newline at end of file diff --git a/docs/analysis/resources/analysis-template.md b/docs/analysis/resources/analysis-template.md index 6d2cbd3..f4eb661 100644 --- a/docs/analysis/resources/analysis-template.md +++ b/docs/analysis/resources/analysis-template.md @@ -91,13 +91,13 @@ _PROJECT_ is a **graduated** project of CNCF. This means that the project should _PROJECT_ is an **incubating** project of CNCF. This means that the project should be [*developing*][criteria-doc] professional-quality documentation alongside the project code. -| Criterion | Rating (1-5) | -| --- | --- | -| Information architecture | (rating value) | -| New user content | (rating value) | -| Content maintainability | (rating value) | -| Content creation processes | (rating value) | -| Inclusive language | (rating value) | +| Criterion | Rating (1-5) | +|----------------------------|----------------| +| Information architecture | (rating value) | +| New user content | (rating value) | +| Content maintainability | (rating value) | +| Content creation processes | (rating value) | +| Inclusive language | (rating value) | _PROJECT_ is an **incubating** project of CNCF. This means that the project should be [*developing*][criteria-doc] professional-quality documentation alongside the project code. -| Criterion | Rating (1-5) | -| --- | ----------------- | -| Communication methods documented | (rating value) | -| Beginner friendly issue backlog | (rating value) | -| “New contributor” getting started content | (rating value) | -| Project governance documentation | (rating value) | +| Criterion | Rating (1-5) | +|-------------------------------------------|----------------| +| Communication methods documented | (rating value) | +| Beginner friendly issue backlog | (rating value) | +| “New contributor” getting started content | (rating value) | +| Project governance documentation | (rating value) | _PROJECT_ is an **incubating** project of CNCF. This means that the project should be [*developing*][criteria-doc] professional-quality documentation alongside the project code. -| Criterion | Rating (1-5) | -| --- | ---------------- | -| Single-source for all files | (rating value) | -| Meets min website req. (for maturity level) | (rating value) | -| Usability, accessibility, and design | (rating value) | -| Branding and design | (rating value) | -| Case studies/social proof | (rating value) | -| SEO, Analytics, and site-local search | (rating value) | -| Maintenance planning | (rating value) | -| A11y plan & implementation | (rating value) | -| Mobile-first plan & impl. | (rating value) | -| HTTPS access & HTTP redirect | (rating value) | -| Google Analytics 4 for production only | (rating value) | -| Indexing allowed for production server only | (rating value) | -| Intra-site / local search | (rating value) | -| Account custodians are documented | (rating value) | +| Criterion | Rating (1-5) | +|---------------------------------------------|----------------| +| Single-source for all files | (rating value) | +| Meets min website req. (for maturity level) | (rating value) | +| Usability, accessibility, and design | (rating value) | +| Branding and design | (rating value) | +| Case studies/social proof | (rating value) | +| SEO, Analytics, and site-local search | (rating value) | +| Maintenance planning | (rating value) | +| A11y plan & implementation | (rating value) | +| Mobile-first plan & impl. | (rating value) | +| HTTPS access & HTTP redirect | (rating value) | +| Google Analytics 4 for production only | (rating value) | +| Indexing allowed for production server only | (rating value) | +| Intra-site / local search | (rating value) | +| Account custodians are documented | (rating value) |