mirror of https://github.com/cncf/techdocs.git
Create 0008-backstage.md (#189)
* Create 0008-backstage.md Added Backstage doc assessment. Signed-off-by: dwelsch-esi <116022979+dwelsch-esi@users.noreply.github.com> * Tested documentation build procedure. Updated assessment with findings. Signed-off-by: dwelsch-esi <116022979+dwelsch-esi@users.noreply.github.com> * Update Backstage assessment website info Added information about site mapping based on Docusaurus plugin documentation. Signed-off-by: dwelsch-esi <116022979+dwelsch-esi@users.noreply.github.com> * updated the website section with appropriate info Signed-off-by: thisisobate <obasiuche62@gmail.com> * Update accessibility section Signed-off-by: thisisobate <obasiuche62@gmail.com> * Completed website assessment and recommendations. Updates and edits to complete the website assessment per @thisisobate. Other minor edits. Signed-off-by: dwelsch-esi <116022979+dwelsch-esi@users.noreply.github.com> * Responses to Backstage doc assessment comments Responses to initial review comments on the Backstage documentation assesment (0008-backstage.md). Signed-off-by: dwelsch-esi <116022979+dwelsch-esi@users.noreply.github.com> * Create user-roles.md Add a short document to define user roles (personas) for the purpose of organizing task-based documentation. Signed-off-by: dwelsch-esi <116022979+dwelsch-esi@users.noreply.github.com> * Move 0008-backstage.md to assessments/0008-backstage Move to project-specific subdirectory. Signed-off-by: dwelsch-esi <116022979+dwelsch-esi@users.noreply.github.com> * Add survey of existing doc pages Add CSV file: survey of existing Backstage doc web pages. Signed-off-by: dwelsch-esi <116022979+dwelsch-esi@users.noreply.github.com> * Add backstage insights summary doc Add Backstage Insights summary document describing findings from Spotify's survey about Backstage adoption. Signed-off-by: dwelsch-esi <116022979+dwelsch-esi@users.noreply.github.com> * In progress: User roles, recommendations. * In progress - writing implementation suggestions. * In progress. Writing implementation recs. * In progress. Writing Implementation section. * In progress - fixed external references Signed-off-by: dwelsch-esi <116022979+dwelsch-esi@users.noreply.github.com> * Update website action items Update website recommendation breakdown. Signed-off-by: dwelsch-esi <116022979+dwelsch-esi@users.noreply.github.com> * Final changes before merging PR. - Separate analysis and implementation. - Clean up references. - Revise intro material. * Changes prior to PR merge - Separate analysis and implementation - Fix references - revise intro * Changes prior to PR merge - Separate analysis and implementation - Fix references - revise intro * adding README to backstage assessment Signed-off-by: Nate W <natew@cncf.io> --------- Signed-off-by: dwelsch-esi <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: thisisobate <obasiuche62@gmail.com> Signed-off-by: Nate W <natew@cncf.io> Co-authored-by: thisisobate <obasiuche62@gmail.com> Co-authored-by: Nate W <natew@cncf.io>
This commit is contained in:
dwelsch-esi
GitHub
parent
78ef77a70f
commit
6dc3441e63
|
|
@ -0,0 +1,10 @@
|
|||
---
|
||||
title: Backstage TechDocs Analysis
|
||||
tags: backstage
|
||||
---
|
||||
|
||||
- [Backstage Analysis](backstage-analysis.md)
|
||||
- [Backstage Implementation](backstage-implementation.md)
|
||||
- [User Roles](user-roles.md)
|
||||
- [Backstage Insights Summary](backstage-insights-summary.md)
|
||||
- [Backstage Docs Survey](backstage-doc-survey.csv)
|
||||
|
|
@ -0,0 +1,498 @@
|
|||
---
|
||||
title: Backstage Documentation Analysis
|
||||
tags: backstage
|
||||
---
|
||||
|
||||
|
||||
Prepared by: Dave Welsch ([@dwelsch-esi][dwelsch-esi-github])<br>
|
||||
Date: 2023-09-01
|
||||
Most recent update: 11/02/2023
|
||||
|
||||
# Introduction
|
||||
|
||||
This document analyzes the effectiveness and completeness of the [Backstage][backstage-io] 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 Backstage documentation. It aims to provide project leaders with an informed understanding of their project documentation and to outline an actionable plan for improvement.
|
||||
|
||||
This document:
|
||||
|
||||
- Analyzes the current Backstage 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 (which contains the technical docs, as well as documentation for contributors and users on the Backstage GitHub repository. The analysis does not include Spotify's Backstage website at https://backstage.spotify.com/.
|
||||
|
||||
The Backstage website and documentation are written in Markdown and are compiled using the Docusaurus static site generator. The site's code is stored on the Backstage GitHub repo.
|
||||
|
||||
**In scope:**
|
||||
- Website: https://backstage.io
|
||||
- Documentation: https://backstage.io/docs
|
||||
- Contributor documentation:
|
||||
- https://github.com/backstage/backstage/README.md
|
||||
- https://github.com/backstage/backstage/CONTRIBUTING.md
|
||||
- Website configuration (Docusaurus): https://github.com/backstage/backstage/microsite
|
||||
- Website content: https://github.com/backstage/backstage/docs
|
||||
|
||||
**Out of scope:**
|
||||
- Backstage plugins: https://backstage.spotify.com/
|
||||
|
||||
|
||||
## 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 Backstage software, aimed at people who intend to use it
|
||||
- **Contributor documentation:** concerns documentation for new and existing contributors to the Backstage OSS project
|
||||
- **Website:** concerns the mechanics of publishing the documentation; includes branding, website structure, and maintainability
|
||||
|
||||
Each section begins with summary ratings based on a rubric with appropriate [criteria][cncf-doc-criteria] for the section, then proceeds to:
|
||||
- **Comments**: observations about the existing documentation, with a focus on how it does or does not help Backstage users achieve their goals.
|
||||
- **Recommendations**: suggested changes that would improve the effectiveness of the documentation.
|
||||
|
||||
An accompanying document, [backstage-implementation.md][implementation-doc], attempts to break 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 should be tracked as a series of Github [issues][backstage-issues].
|
||||
|
||||
|
||||
## How to use this document
|
||||
|
||||
Readers interested only in actionable improvements should skip this document and read [backstage-implementation.md][implementation-doc].
|
||||
|
||||
Readers interested in the current state of the documentation and the reasoning behind the recommendations should read this document or the section pertaining to their area of concern:
|
||||
|
||||
- [Project documentation][proj-doc]
|
||||
- [Contributor documentation][contributor-doc]
|
||||
- [Website and documentation infrrastructure][website]
|
||||
|
||||
|
||||
### Recommendations, requirements, and best practices
|
||||
|
||||
Notwithstanding the fact that this analysis measures documentation against CNCF project maturity standards, 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 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.
|
||||
|
||||
|
||||
# Project documentation
|
||||
|
||||
| Criteria | 1 | 2 | 3 | 4 | 5 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Information architecture | | ✔︎ | | | |
|
||||
| New user content | | | | ✔︎ | |
|
||||
| Content maintainability | | | ✔︎ | | |
|
||||
| Content creation processes | | | ✔︎ | | |
|
||||
| Inclusive language | | | | ✔︎ | |
|
||||
|
||||
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: project documentation
|
||||
|
||||
Backstage is a platform for organizing and managing software projects. This complicates the documentation, because it can be difficult to distinguish among several levels of involvement with Backstage:
|
||||
|
||||
1. Use of Backstage as an organizational contributor (coder, DevOp, tech writer) to catalog, create, or document software.
|
||||
2. Administration of a Backstage instance ("app" in Backstage nomenclature), including installation, deployment, software upgrades, configuration, and customization using plugins.
|
||||
3. Extending a Backstage app, including writing plugins and modifying existing plugins.
|
||||
4. Modification or extension of the Backstage platform.
|
||||
|
||||
This complexity necessitates clear definitions of roles so that use cases can be documented, indexed, found, and used. The four levels described above suggest that documentation should be organized under at least four roles:
|
||||
|
||||
1. Using Backstage for software development: end user.
|
||||
2. Installing and maintaining a Backstage app for an organization: Backstage admin.
|
||||
3. Extending a Backstage app: DevOp or internal tooling developer.
|
||||
4. Extending the Backstage platform: contributing developer.
|
||||
|
||||
### Overall Issues
|
||||
|
||||
The main issues with the Backstage documentation are:
|
||||
1. Lack of organization around user roles, and
|
||||
2. Lack of instructional content that defines tasks for each role and provides explicit instructions to accomplish these tasks.
|
||||
|
||||
For example, the [Overview][backstage-io-overview] contains valuable high-level conceptual information, including a list of [benefits][backstage-io-overview-benefits] to particular user roles (engineering managers, developers, platform engineers). This demonstrates awareness of user roles that needs to be extended throughout the documentation.
|
||||
|
||||
There are installation and configuration instructions in [Getting Started][backstage-doc-getting-started]. However:
|
||||
1. The instructions describe a local installation.
|
||||
2. The user documentation, for the most part, lacks procedural information.
|
||||
|
||||
The following sections contain brief analyses of each element of the Project Documentation rubric.
|
||||
|
||||
### Information architecture
|
||||
|
||||
**Conceptual content** is abundant throughout the Backstage documentation. This is good, because using Backstage effectively requires a thorough understanding of its information model.
|
||||
|
||||
The documentation seems **feature complete**. All software features are documented.
|
||||
|
||||
**Instructional content** is a weakness of the Backstage docs. In many cases, tasks required of each role are missing, as are instructions for completing these tasks. Instructional material for the most common use cases (**"happy path"**) should support learning (tutorials) as well as doing (procedures). Where instructional content exists, it is often:
|
||||
|
||||
- Not aimed at a defined user,
|
||||
- Not clearly identified as instructional content, or
|
||||
- Intermingled or confused with reference information (for example, many configuration "how-tos" are in the form of a list of YAML properties).
|
||||
|
||||
**Escalation** options (FAQs, Troubleshooting docs) exist for most Backstage functionality. As well, the contributor community provides robust support (GitHub [issues][backstage-issues] and discussion channels).
|
||||
|
||||
**Reference information** exists, including for **APIs**, but is scattered throughout the documentation.
|
||||
|
||||
**Organizing individual pages**: A [survey of the existing documentation][doc-survey] suggests a general issue with many individual pages: trying to include too much information on one page. Often a task is mixed with reference information or with more conceptual information than is necessary to support the task. Effective documentation focuses on one type of information per page, especially when presenting instructional content: the page should present only what information is necessary to do the task, and nothing else. Examples of information that should be on a different (but linked) page: Explanations of the task's purpose; command references (except the exact commands needed to complete the task); and examples, such as config file entries (again, except as necessary).
|
||||
|
||||
It's not clear that the documentation is completely **up to date**, although [release notes][backstage-doc-rn] exist and are easily findable.
|
||||
|
||||
Examples:
|
||||
|
||||
* https://prometheus.io/docs/introduction/overview/
|
||||
* https://kubernetes.io/docs/home/
|
||||
|
||||
|
||||
### New user content
|
||||
|
||||
**New user** content is present and findable ("**signposted**"), including **installation** instructions for all applicable **OSes**. However, the [Getting Started][backstage-doc-getting-started] instructions don't distinguish between administrator and developer end-user roles. [Deployment][backstage-doc-deployment] describes various scenarios for administrators, but doesn't provide end-to-end instructions. There is no clear workflow **path** after installation.
|
||||
|
||||
There is **example content** available, including tutorials for a variety of tasks and a very nice [demo server][backstage-demo].
|
||||
|
||||
Examples:
|
||||
|
||||
* https://falco.org/docs/getting-started/
|
||||
* https://prometheus.io/docs/introduction/first_steps/
|
||||
|
||||
|
||||
### Content maintainability & site mechanics
|
||||
|
||||
The documentation is **searchable**. There does not seem to be a **localization** framework. There doesn't currently seem to be any kind of localization effort.
|
||||
|
||||
There does not seem to be any mechanism for **versioning** documentation content.
|
||||
|
||||
Examples:
|
||||
|
||||
* https://github.com/kubernetes/website
|
||||
|
||||
|
||||
### Content creation processes
|
||||
|
||||
The procedures for duplicating the documentation locally and for contributing documentation are [documented][backstage-microsite] but are [not easily findable][backstage-doc-contrib].
|
||||
|
||||
These procedures are presumably included in any updates to (and subsequent **release** of) the project code (since the doc is in the same GitHub repo). **Reviewers and approvers** are presumably the Backstage OSS community at large. It would be nice if this situation were made clear explicitly.
|
||||
|
||||
The website does not have a clear individual **owner or maintainer**.
|
||||
|
||||
Examples:
|
||||
|
||||
* https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md (clearly documented maintainers)
|
||||
* https://thanos.io/tip/contributing/how-to-contribute-to-docs.md/
|
||||
|
||||
|
||||
### Inclusive language
|
||||
|
||||
I found no content that uses non-recommended words as documented by the [Inclusive Naming Initiative][inclusive-naming] website.
|
||||
|
||||
The website makes occasional use of words like "simple" and "easy", but avoids explicitly ableist language.
|
||||
|
||||
|
||||
## Recommendations: project documentation
|
||||
|
||||
The following sections contain recommendations for improvements to the Backstage project documentation. These recommendations are for broad improvements that would greatly increase documentation effectiveness. For details, see [Implementation][implementation]
|
||||
|
||||
|
||||
### Clarify user roles and objectives
|
||||
|
||||
Any systemic improvement to the Backstage documentation hinges on clearly defining and documenting user roles. This is a first step in defining any documentation set, but the nature of Backstage makes it especially important here.
|
||||
|
||||
The example roles given in the [comments][proj-doc-comments] have been carried over to the [Implementation][implementation] section. Contributors with a greater understanding of how Backstage is used should feel free to modify this list if it serves the needs of the project, keeping in mind that the purpose of the user roles is to organize the task-based documentation.
|
||||
|
||||
|
||||
### Develop instructional documentation
|
||||
|
||||
Most of the Backstage documentation seems to have evolved from architecture and design documentation. This makes it very rich in conceptual material and reference documentation, but weak in user-oriented instructional documentation.
|
||||
|
||||
"Instructional documentation" is a broad category that includes such traditional documentation artifacts as tutorials; getting started guides; procedural recipes or "cookbooks"; runbooks; and how-to guides.
|
||||
|
||||
For every user role:
|
||||
|
||||
**Define use cases**: Define the common use cases for each role. Some typical examples:
|
||||
|
||||
*Administrator*: Installation; deployment; configuration; maintenance; upgrades; extension (plugins); disaster recovery.
|
||||
|
||||
*User (developer)*: Development environment setup; Adding an existing element; creating a new element; creating a template; viewing projects; searching; creating documentation; CI/CD; deploying; reverting a deployment.
|
||||
|
||||
**Write procedures**: For each use case, develop instructional content, including: "happy path" procedures that can be followed by anyone familiar with the product generally; examples; troubleshooting guides; and for new users, tutorials.
|
||||
|
||||
### Reorganize the documentation site
|
||||
|
||||
Right now different types of documentation (conceptual/architectural; instructional; reference) for different user roles are intermixed throughout the documentation site.
|
||||
|
||||
**Organize by role and task**
|
||||
|
||||
The site should be reorganized based on an overarching principle of grouping together documentation needed by a particular user role for a particular set of tasks. This sounds daunting, but it's the schema behind a traditional developer documentation suite, which can be used as a model. For an example of such a doc suite, see [this blog post][esi-doc-suite]. Or [this one][esi-doc-spec] on how to think about a doc specification. [This survey of the existing Backstage doc pages][doc-survey] suggests where each page might fit if the doc were reorganized in this manner.
|
||||
|
||||
**Provide adequate navigation signals**
|
||||
|
||||
Reorganizing the site will make the documentation more usable. Not to be overlooked is the companion task of making the documentation *findable*. This involves creating adequate tables of contents (TOCs), indexes, and a glossary to help navigate the site. Much of this is automated by the static site generator (currently *Docusaurus*), but it's the writer's responsibility to assure that these navigation aids are adequate.
|
||||
|
||||
|
||||
# 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: contributor documentation
|
||||
|
||||
A unique feature of Backstage is that user and contributor roles exist on a spectrum; plugins designed or modified to serve a particular organization can be contributed to the Backstage project, or can originate there in anticipation of a particular organization's need. As a result, documentation for project contributors is intermingled, and easily confused, with instructions for admin users trying to expand functionality by modifying or adding code, especially plugins.
|
||||
|
||||
|
||||
### Communication methods documented
|
||||
|
||||
Communication channels are clearly documented on the [Community][backstage-community] page of the website, including **message channels**, **newsletters** and **adoption meetings**. There is some minor conflation of commercially sponsored content on the community page.
|
||||
|
||||
The **[GitHub][backstage-backstage] repository** is directly linked from the main menu. There are 22 related repositories listed on the [Backstage project page][backstage-github-project]. A little digging is required to suss out the purpose of some of these projects.
|
||||
|
||||
Examples:
|
||||
https://kubernetes.io/community/
|
||||
|
||||
|
||||
### Beginner friendly issue backlog
|
||||
|
||||
The backlog is robustly **triaged** and documented. A **"good first issue"** label is available and prominently recommended. Issues are **well documented** with complete descriptions.
|
||||
|
||||
There are quite a few **stale backlog items** open in the backlog list. Many, perhaps a majority, of these seem to be plugin requests.
|
||||
|
||||
### New contributor getting started content
|
||||
|
||||
The Backstage OSS **community** is visible and accessible on a [community page][backstage-community] reached via a top-level menu item on the website. There is an active [Discussions][backstage-discussion] board in the GitHub repo.
|
||||
|
||||
**[Contributor guidelines][backstage-contrib]** are provided.
|
||||
|
||||
**Help** is available in any of the discussion groups and through a [community page][backstage-github-community] on GitHub. Help resources are not linked from the Getting Started documentation.
|
||||
|
||||
Backstage is listed in the [Clotributor][clotributor] tool.
|
||||
|
||||
Examples:
|
||||
|
||||
* https://github.com/helm/community
|
||||
* https://github.com/backstage/community
|
||||
|
||||
### Project governance documentation
|
||||
|
||||
Governance is clearly documented in [GOVERNANCE.md][backstage-governance].
|
||||
|
||||
Examples:
|
||||
|
||||
* https://github.com/kubernetes/steering
|
||||
|
||||
|
||||
## Recommendations: contributor documentation
|
||||
|
||||
As an open source project, Backstage looks healthy and well run.
|
||||
|
||||
The only recommendation here is to disentangle the contributor documentation from the product documentation, as described in the [Information architecture recommendations][info-arch-recommend].
|
||||
|
||||
|
||||
# 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 | | | ✔︎ | | |
|
||||
| SEO, Analytics, and site-local search | | | | | ✔︎ |
|
||||
| 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: website
|
||||
|
||||
### Single-source requirement
|
||||
|
||||
The source files for the website and technical documentation reside in two separate directories of the Backstage GitHub repo, built as a single unit by *Docusaurus*. There is no separate **website repo**.
|
||||
|
||||
The strategy for **generating the docs** is documented but obscure.
|
||||
|
||||
### Minimal website requirements
|
||||
|
||||
Listed and acknowledged below are the (cumulative) _minimal_ website requirements for projects based on their [maturity level][cncf-maturity-stages]: sandbox, incubating, graduated and archived.
|
||||
|
||||
| Maturity | Requirement | Met? |
|
||||
| --- | --- | --- |
|
||||
| Sandbox | Majority of [Website guidelines][cncf-website-guidelines] satisfied | yes |
|
||||
| Sandbox | [Docs analysis][cncf-docs-howto] [submitting a request][cncf-servicedesk] completed. | yes |
|
||||
| Incubating | All [Website guidelines][cncf-doc-criteria] satisfied | no |
|
||||
| Incubating | Request docs (re-)analysis through CNCF [service desk][cncf-servicedesk] | yes |
|
||||
| Incubating | **Project doc**: stakeholders (roles) identified and doc needs documented | no |
|
||||
| Incubating | **Project doc**: Hosted directly | yes |
|
||||
| Incubating | **Project doc**: Comprehensive, addressing most stakeholder needs | no |
|
||||
| Graduated | [Docs analysis][cncf-docs-howto]: all analysis follow-through actions are complete | no |
|
||||
| Graduated | **Project doc** fully addresses needs of key stakeholders | no |
|
||||
| Archived | The website repo is in an [archived state][github-archiving] | n/a |
|
||||
| Archived | Archived status of the project is obvious to site visitors | n/a |
|
||||
| Archived | Link to successor project website and/or migration documentation (if it exists) | n/a |
|
||||
|
||||
|
||||
### Branding and design
|
||||
|
||||
The Backstage **brand** is easily recognizable through the logo and color scheme. The scheme is **used consistently** across the website and docs.
|
||||
|
||||
The website **typography** is easy to read.
|
||||
|
||||
Examples:
|
||||
|
||||
* https://helm.sh/
|
||||
|
||||
|
||||
### Case studies/social proof
|
||||
|
||||
**Case studies** and **testimonials** are not prominent and are not readily findable from the website. There is no **logo wall** of participating organizations.
|
||||
|
||||
The project has an **active blog**. **Community discussions** are available on the website.
|
||||
|
||||
Examples:
|
||||
|
||||
* https://www.fluentd.org/testimonials (user testimonials)
|
||||
* https://goharbor.io/ (logo wall)
|
||||
* https://blog.rook.io/ (blog)
|
||||
|
||||
|
||||
### SEO, Analytics and site-local search
|
||||
|
||||
**Analytics**
|
||||
|
||||
- **Analytics** is enabled for the production server using **GA4**.
|
||||
- Analytics is **disabled for all other deploys**.
|
||||
- **Page-not-found (404) reports** are easily generated from the site.
|
||||
|
||||
**Site indexing**
|
||||
|
||||
**Indexing** is supported for the **production server**. Indexing is **disabled for previews** and **non-default builds** automatically with `plugin-sitemap`.
|
||||
|
||||
**Search**
|
||||
|
||||
Local intra-site **search** is available from the website.
|
||||
|
||||
**Custodians**
|
||||
|
||||
The current **custodian(s)** of the following accounts are **not** clearly documented: analytics, Google Search Console, site-search (such as Google CSE or Algolia).
|
||||
|
||||
|
||||
### Maintenance planning
|
||||
|
||||
The **website tooling** (Docusaurus static site build) is well supported.
|
||||
|
||||
**Cultivation of website maintainers** from within the community is inadequate.
|
||||
|
||||
I tested the instructions for using `yarn` to build the website. The **site build time** was under 30 seconds for a local build on a Mac M1. Maintainers have sufficient **permissions** to download and build the doc. Checking in the doc requires a PR and approval from a project maintainer.
|
||||
|
||||
Examples:
|
||||
|
||||
* http://kubernetes.io
|
||||
|
||||
### Usability, accessibility and devices
|
||||
|
||||
Backstage.io is partially conformant with [WCAG 2.1 level AA][wcag-understanding] with respect to **accessibility**.
|
||||
|
||||
|
||||
## Recommendations: website
|
||||
|
||||
### Single-source repo
|
||||
|
||||
The documentation is isolated from the code by virtue of being in its own directories; however, its location and build instructions are hard to find. Write explicit instructions for contributing to documentation. Make these instructions prominent in the contributor guidelines. Emphasize the importance of keeping the documentation directories separate from code.
|
||||
|
||||
An even better plan would be to extract the Docusaurus configurations and website documentation to their own repository. The Backstage project already has many repositories. Creating one more for documentation would make the project organization cleaner and make it easier to contribute to the project documentation.
|
||||
|
||||
|
||||
### Minimum website requirements for maturity level
|
||||
|
||||
To meet the maturity level standards for a graduated project, the following aspects should be updated as described in [Project documentation][proj-doc]:
|
||||
|
||||
- Identify the project and product stakeholder roles.
|
||||
- Analyze stakeholder needs.
|
||||
- Update and reorganize the documentation with respect to user orientation and task-based support of use cases.
|
||||
|
||||
|
||||
### Case studies/social proof
|
||||
|
||||
Implement a **logo wall** of participating organizations, with links to testimonials and/or case studies.
|
||||
|
||||
|
||||
### SEO, Analytics and site-local search
|
||||
|
||||
Add documentation and website custodians to the project maintainer lists in `OWNERS.md` and wherever else project maintainers are documented.
|
||||
|
||||
|
||||
### Maintenance planning
|
||||
|
||||
Add a prominent call for website and documentation maintainers in the project introduction alongside the call for code maintainers.
|
||||
|
||||
|
||||
### Accessibility
|
||||
|
||||
Improve compliance in these areas:
|
||||
- **Images** should have alternative text.
|
||||
- **Links** should have discernible text.
|
||||
|
||||
|
||||
<!--- References --->
|
||||
|
||||
[backstage-backstage]: https://github.com/backstage/backstage
|
||||
[backstage-community]: https://backstage.io/community
|
||||
[backstage-contrib]: https://github.com/backstage/backstage/CONTRIBUTING.md
|
||||
[backstage-demo]: https://demo.backstage.io/catalog?filters%5Bkind%5D=component&filters%5Buser%5D=owned
|
||||
[backstage-discussion]: https://github.com/backstage/backstage/discussions
|
||||
[backstage-doc-contrib]: https://backstage.io/docs/getting-started/getting-involved#write-documentation-or-improve-the-website
|
||||
[backstage-doc-deployment]: https://backstage.io/docs/deployment/
|
||||
[backstage-doc-getting-started]: https://backstage.io/docs/getting-started/
|
||||
[backstage-doc-rn]: https://backstage.io/docs/releases/v1.17.0
|
||||
[backstage-github-community]: https://github.com/backstage/community
|
||||
[backstage-github-project]: https://github.com/backstage
|
||||
[backstage-governance]: https://github.com/backstage/backstage/blob/master/GOVERNANCE.md
|
||||
[backstage-insights-summary]: ./backstage-insights-summary.md
|
||||
[backstage-issues]: https://github.com/backstage/backstage/issues
|
||||
[backstage-io-overview-benefits]: https://backstage.io/docs/overview/what-is-backstage#benefits
|
||||
[backstage-io-overview]: https://backstage.io/docs/overview/what-is-backstage
|
||||
[backstage-io]: https://backstage.io
|
||||
[backstage-microsite]: https://github.com/backstage/backstage/tree/master/microsite
|
||||
[clotributor]: https://clotributor.dev/
|
||||
[cncf-doc-criteria]: criteria.md
|
||||
[cncf-doc-criteria]: https://github.com/cncf/techdocs/blob/main/assessments/criteria.md
|
||||
[cncf-docs-howto]: https://github.com/cncf/techdocs/blob/main/assessments/howto.md
|
||||
[cncf-maturity-stages]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations
|
||||
[cncf-servicedesk]: https://servicedesk.cncf.io
|
||||
[cncf-website-guidelines]: ../../docs/website-guidelines-checklist.md
|
||||
[dwelsch-esi-github]: https://github.com/dwelsch-esi/
|
||||
[esi-doc-spec]: https://expertsupport.com/library/quick-and-easy-document-specifications/
|
||||
[esi-doc-suite]: https://expertsupport.com/library/the-ideal-documentation-suite-for-software-developers/
|
||||
[github-archiving]: https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories
|
||||
[implementation-doc]: ./backstage-implementation.md
|
||||
[inclusive-naming]: https://inclusivenaming.org
|
||||
[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119
|
||||
[wcag-understanding]: https://www.w3.org/WAI/WCAG21/Understanding/
|
||||
<!--- internal refs --->
|
||||
[contrib-doc-rec]: #recommendations-contributor-documentation
|
||||
[contributor-doc]: #contributor-documentation
|
||||
[doc-survey]: ./Backstage%20doc%20survey.csv
|
||||
[implementation]: #implementation
|
||||
[info-arch-recommend]: #recommendations
|
||||
[proj-doc-comments]: #comments-project-documentation
|
||||
[proj-doc-rec]: #recommendations-project-documentation
|
||||
[proj-doc]: #project-documentation
|
||||
[user-roles]: #user-roles
|
||||
[website-rec]: #recommendations-website
|
||||
[website]: #website
|
||||
|
|
@ -0,0 +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
|
||||
|
|
|
@ -0,0 +1,238 @@
|
|||
---
|
||||
title: Implementing Backstage Doc Improvements
|
||||
tags: backstage
|
||||
---
|
||||
|
||||
# Introduction
|
||||
|
||||
This document provides actionable suggestions for improving the Backstage technical documentaiton.
|
||||
|
||||
For an analysis and general discussion of recommendations on Backstage technical documentation, see [backstage-analysis.md][backstage-analysis]].
|
||||
|
||||
## Recommendations, requirements, and best practices
|
||||
|
||||
Notwithstanding the fact that this analysis measures documentation against CNCF project maturity standards, 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 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:
|
||||
|
||||
- Fill gaps in instructional documentation for all stakeholder roles, including project contributors.
|
||||
- Organize and "signpost" documentation by role and task so that stakeholders can find documentation that supports their roles' activities.
|
||||
|
||||
# Definitions
|
||||
|
||||
These implementations rely on the following definitions.
|
||||
|
||||
## Organization
|
||||
|
||||
It is assumed that Backstage is adopted by a medium-to-large *organization* (*org*) made up of a number of *groups*.
|
||||
|
||||
## Group
|
||||
|
||||
A group is defined by its responsibility for one or more software *products* that are manageable in Backstage.
|
||||
|
||||
## Product
|
||||
|
||||
Products can include but are not limited to: internal and external toolkits and APIs; components; databases; and web-based and standalone applications.
|
||||
|
||||
A group needs 1) visibility into the org's entire corpus of products, and 2) to publicize its own software products to the org.
|
||||
|
||||
## Developer
|
||||
|
||||
Members of a group can have various functional and organizational roles, including: software engineer; dev-op; QA engineer; software architect; network engineer; engineering manager; and many others. These implementations refer to a group member generically as a *developer* (*dev*).
|
||||
|
||||
## Contributor
|
||||
|
||||
The org has ties to the Backstage open source software (OSS) project through developers who contribute to the project and who participate in discussions, newsgroups, and other community forums. These OSS participants, regardless of their employer or job function, are called *contributors*.
|
||||
|
||||
# User Roles
|
||||
|
||||
The only distinctions among Backstage users relevant to this implementation discussion are among *user roles*. User roles are defined to organize documentation recommendations. The following table summarizes the user roles that have been identified for that purpose.
|
||||
|
||||
| User Role | Use Cases |
|
||||
| --- | --- |
|
||||
| Evaluator | Someone who is trying to decide whether to adopt Backstage into an organization. |
|
||||
| Administrator | An IT or DevOps professional responsible for standing up and maintaining an organization's instance of Backstage (the *Backstage app*). |
|
||||
| Developer | The Backstage "end user". A developer, part of a group within an organization. Typically but not always a technical contributor, the developer uses Backstage to learn about and use software components within the org and to publish and document their group's software. |
|
||||
| Integrator | A developer who modifies an org's Backstage app (typically by writing or modifying a plugin) to add functionality required by the org. This modification might or might not then be contributed back to the Backstage OSS project. |
|
||||
| Contributor | A developer who supplies a work product (code or documentation, e.g.) to the Backstage open-source project, or who volunteers to participate by providing services (reviews, discussion, or committee membership, e.g.). Much of the contributor documentation is specifically for integrators who contribute plugins or code to the project. |
|
||||
|
||||
|
||||
**A note about adoption champions**: A survey of Backstage adopters entitled "Backstage Insights" was undertaken by Spotify. The survey is summarized briefly in [this document][backstage-insights-summary]. Backstage Insights identifies another role, the *Champion*. Due to the complexity and level of commitment needed to adopt Backstage, Backstage Insights deems the champion necessary for an organization to successfully adopt Backstage. Adoption and the champion role are not addressed in the Backstage documentation and are beyond the scope of this analysis. They are important considerations, however, that should be addressed by any organization and for which further exploration and documentation would be valuable.
|
||||
|
||||
# Implementation: Fill gaps in instructional documentation
|
||||
|
||||
"Instructional documentation" is a broad category that includes such traditional documentation artifacts as tutorials; getting started guides; procedural recipes or "cookbooks"; runbooks; and how-to guides. We recommend that the project first ensure that basic task documentation is covered, then build out tutorials, cookbooks, and more specialized documentation.
|
||||
|
||||
Broadly, the recommendation here is to do this:
|
||||
|
||||
1. For every [user role][user-roles], define the common use cases for each role.
|
||||
2. For each use case, develop instructional content, including:
|
||||
- "Happy path" procedures that can be followed by anyone familiar with the product generally
|
||||
- examples
|
||||
- troubleshooting guides
|
||||
- for new users, tutorials
|
||||
|
||||
There is already some instructional content in the Backstage documentation. In many cases, it is intermingled with conceptual and reference information. A common example of this is in configuration instructions. Many configurations are embodied in YAML files, and the documentation web page for the configuration amounts to an explanation of the contents of a particular config file. In such cases, the page should be rewritten as two or three distinct pages: a step-by-step explanation (not just of the file contents, but where to put it, how to load it, and so on); a configuration reference that exhaustively lists all elements that the file can contain; and if necessary an introduction explaining what the configuration controls.
|
||||
|
||||
The sections below give recommendations for the most important instructional documentation improvements to Backstage for each user role.
|
||||
|
||||
## Evaluator
|
||||
|
||||
The website guidelines contain elements that are intended to help evaluators decide whether the product is suitable to their needs, such as a logo wall and case studies.
|
||||
|
||||
Technical documentation contains little that is actually geared toward evaluators, but a good technical overview – valuable to all stakeholders – is essential in evaluating the product.
|
||||
|
||||
## Administrator
|
||||
|
||||
The following artifacts need to be written and made findable for administrators.
|
||||
|
||||
1. A server installation and setup guide for administrators. Provide clear, step-by-step instructions for downloading and deploying Backstage to an organization.
|
||||
|
||||
Instructions can also be provided for installing a local, group-level, or test deployment, but these instructions should be separate and clearly labeled as non-production.
|
||||
|
||||
1. An Administrator Guide, with instructions on how to do such things as:
|
||||
- Start and stop the Backstage server
|
||||
- Install and configure Backstage plugins
|
||||
- Manage the many software dependencies for Backstage and its plugins
|
||||
- Maintain the Backstage database
|
||||
- Upgrade and downgrade the Backstage release verison
|
||||
- Troubleshoot common problems
|
||||
- Tune server performance
|
||||
|
||||
## Developer
|
||||
|
||||
The following artifacts need to be written and made findable for developers.
|
||||
|
||||
1. A getting started guide for developers. Provide a clear work path that describes how to:
|
||||
1. Downloead and install any necessary software components
|
||||
1. Integrate Backstage with an existing development environment
|
||||
|
||||
1. A User Guide for developers. Provide clear instructions for these tasks:
|
||||
- Adding an existing product to Backstage
|
||||
- Creating a new product in Backstage
|
||||
- Updating a product in Backstage
|
||||
- Documenting a product in Backstage
|
||||
- Deprecating and retiring a product from Backstage
|
||||
- Searching for a component in Backstage
|
||||
|
||||
|
||||
## Integrator
|
||||
|
||||
There are a dizzying array of issues with writing, modifying, and maintaining plugins in Backstage. This is not a detailed recipe for documenting those issues. For integrators, at a high level, a program should be undertaken to:
|
||||
|
||||
1. Organize integrator tasks from most basic and common (write a simple plugin; decide between backend and frontend plugin) to more complex (Integrate with external systems; use a proxy; implement authentication).
|
||||
2. Where possible, using the exisitng documentation as a starting point, write step-by-step procedures for discrete integration tasks (starting with how to write a basic plugin).
|
||||
3. Organize existing reference and conceptual information (such as API references and architecture discussions) into supporting documentation, referenced from the integration tasks.
|
||||
|
||||
|
||||
## Contributor
|
||||
|
||||
For a plugin-dependent project like Backstage, it's vital that community members contribute plugins, for two reasons:
|
||||
|
||||
1. To expand the base functionality of Backstage by covering common use cases
|
||||
2. To provide complete examples of how plugins are structured, written, and added to the project
|
||||
|
||||
Contributor documentation should be in Markdown files in the Backstage GitHub repo and should be limited to how to contribute software to the product. "How to write a plugin" documentation should be included in the website-based doc as described above.
|
||||
|
||||
# Organize and "signpost" documentation
|
||||
|
||||
Right now different types of documentation (conceptual/architectural; instructional; reference) for different user roles are intermixed throughout the documentation site.
|
||||
|
||||
Below is a proposed organization for Backspace by user role, based on a fairly typical documentation set for developer-oriented software. Using exactly this organization is not important. What is important, again, is to document use cases, broken down into tasks, by user role. The documentation should reflect the needs of each user role and be organized such that any user has a clear path to learning the software and becoming proficient as quickly as possible.
|
||||
|
||||
Some documents are used by more than one user role. These docs are listed first under the heading **Common**.
|
||||
|
||||
## Common
|
||||
|
||||
| Document | Description |
|
||||
| --- | --- |
|
||||
| Technical overview | A discussion of what the product is and what problems it solves. Ideally, the discussion starts with a summary and provides explanations of increasing depth to address to satisfy different audiences (evaluator -> developer -> contributor, e.g.). |
|
||||
| Release notes | Release-specific information, including: new features; performance improvements; bugs and known issues; deprecated features; software dependency changes; and experimental or beta features. |
|
||||
| Glossary | A dictionary of product-specific terms. Also commonly includes domain- and industry-specific terms that are necessary to understanding the product. |
|
||||
| Knowledge base | An encyclopedic collection of related background, conceptual, and reference information that doesn't fit elsewhere in the documentation. Similar to a FAQ, but more structured, more searchable and, therefore, more useful. |
|
||||
|
||||
|
||||
## Evaluator
|
||||
|
||||
| Document | Description |
|
||||
| --- | --- |
|
||||
| Logo wall | Not a technical document, but a *de rigeur* feature on a product website these days. The logo wall shows at a glance an instantly recognizable selection of organizations that use the product. The logos typically link to testimonials or to the organizations' own websites. |
|
||||
| Case studies | Another element on a product website that is as much marketing as technical material, a case study nonetheless helps an evaluator decide whether to adopt the product. A handful of well written case studies is sufficient. |
|
||||
|
||||
## Administrator
|
||||
|
||||
| Document | Description |
|
||||
| --- | --- |
|
||||
| CLI reference | An indexed reference to the command-line interface. The Backstage CLI does a wide variety of tasks and is used both the administrator and by developers. |
|
||||
| Installation and configuration guide | A guide to downloading, installing, and configuring an organization-wide Backstage instance ("app"). |
|
||||
| Administrator guide | Contains all tasks the administrator needs to maintain the Backstage app: onboarding developers; installing plugins; starting, stopping, upgrading, and troubleshooting the app; using containers; evaluating and tuning server performance. |
|
||||
|
||||
|
||||
## Developer
|
||||
|
||||
| Document | Description |
|
||||
| --- | --- |
|
||||
| Getting started guide | A document that usually walks a developer through setting up a development environment (for a language or API). In the case of Backstage, this is more of an integration with their existing environment. Nonetheless, this should explain how to configure all the tools the developer needs to begin using Backstage. |
|
||||
| Developer guide | Contains all tasks that the developer needs to use the Backstage app under normal circumstances: adding, modifying, and searching for products; writing documentation; using templates. |
|
||||
| CLI reference | An indexed reference to the command-line interface. The Backstage CLI does a wide variety of tasks and is used both the administrator and by developers. |
|
||||
| Tutorials | Tasks that are good candidates for tutorials are difficult, often-used tasks that must be mastered to use the product effectively. Many of these are probably in daily use by developers. |
|
||||
| Cookbooks | There might be specialized tasks required of developers by an organization that should be documented, especially if they are performed infrequently. |
|
||||
|
||||
|
||||
## Integrator
|
||||
|
||||
| Document | Description |
|
||||
| --- | --- |
|
||||
| Technical overview | Same as the common technical overview, but an integrator will need more detail about the plugin architecture. |
|
||||
| Cookbooks | The integrator will need to write plugins. This encompasses a large body of task knowledge. The best way to document these is as a collection of tasks or procedures explaining how to complete each task. Even with a comprehensive collection of task documents, some creativity is probably needed by the integrator, since every new plugin by definition is solving a new problem. |
|
||||
|
||||
|
||||
## Contributor
|
||||
|
||||
| Document | Description |
|
||||
| --- | --- |
|
||||
| GitHub Instructions | Contributing a plugin to Backstage is essentially an exercise in creating and shepherding a pull request through the Backstage community process. This can be documented entirely in GitHub, or it can be a separate section in the Backstage documentation. Regardless, the contributing instructional material should be separate from the integration/"How to write a plugin" material. |
|
||||
|
||||
|
||||
# Website and documentation infrastructure
|
||||
|
||||
|
||||
## Single-source repo
|
||||
|
||||
Move the Backstage documentation out of the [Backstage repo][backstage-github-project] and into its own repo within the [Backstage project][backstage-backstage]. Write explicit instructions for contributing to documentation and place them in the repo README.
|
||||
|
||||
In the meantime, put references to the documentation contributing and build instructions alongside the project code instructions in the contributor documentation in the Backstage repo.
|
||||
|
||||
|
||||
## Case studies/social proof
|
||||
|
||||
Implement a **logo wall** of participating organizations, with links to testimonials or the organizations' websites. Write or solicit a handful of representative case studies and link them from the website.
|
||||
|
||||
|
||||
|
||||
## SEO, Analytics and site-local search
|
||||
|
||||
Add documentation and website custodians to the project maintainer lists in `OWNERS.md` and wherever else project maintainers are documented.
|
||||
|
||||
|
||||
## Maintenance planning
|
||||
|
||||
Add a prominent call for website and documentation maintainers in the project introduction alongside the call for code maintainers.
|
||||
|
||||
|
||||
## Accessibility
|
||||
|
||||
Improve compliance in these areas:
|
||||
- **Images** should have alternative text.
|
||||
- **Links** should have discernible text.
|
||||
|
||||
|
||||
<!--- References --->
|
||||
|
||||
[backstage-analysis]: ./backstage-analysis.md
|
||||
[backstage-backstage]: https://github.com/backstage/backstage
|
||||
[backstage-github-project]: https://github.com/backstage
|
||||
[backstage-insights-summary]: ./backstage-insights-summary.md
|
||||
[user-roles]: #user-roles
|
||||
|
|
@ -0,0 +1,76 @@
|
|||
# Backstage Insights
|
||||
|
||||
This document briefly summarizes the research, branded "Backstage Insight," done at Spotify in 2022 to identify ways to drive adoption of Backstage.
|
||||
|
||||
## Why Backstage Adoption is Hard
|
||||
|
||||
Backstage is a complex system that must be adopted universally throughout an organization in order to reap its full benefits.
|
||||
|
||||
### Definition of "Adoption"
|
||||
|
||||
Adoption here means:
|
||||
|
||||
1. An organization-wide instance ("app") of Backstage must be installed, run, maintained, and actively updated with new capabilities via plugins;
|
||||
2. All development groups in the organization must use Backstage to, at the least, catalog their projects. Additional benefits accrue if groups also:
|
||||
1. Manage documentation in Backstage;
|
||||
2. Use templates in Backstage to create new software artifacts; and
|
||||
3. Automate development using Backstage, including integrating Backstage with other development support systems.
|
||||
3. Backstage must be recognized throughout the organization as the "source of truth" about all software development within the organizaiton.
|
||||
|
||||
### Barriers to Adoption
|
||||
|
||||
Backstage Insights identifies three types of barriers to adoption: technical, cultural, and combination.
|
||||
|
||||
*Technical* barriers are the effort required for groups to adopt Backstage for software projects, including writing or adapting plugins for features unique to a particular project or group.
|
||||
|
||||
Backstage is a very flexible product with vast potential to adapt to variations in organizational infrastructure and workflows. The flipside is that Backstage is complex, and almost always requires significant investment of talent and resources to implement fully.
|
||||
|
||||
*Cultural* barriers are institutional resistance to adopting Backstage due to:
|
||||
- Unwillingness to devote resources to adopting and maintaining Backstage;
|
||||
- Skepticism of the value of Backstage;
|
||||
- General resistance to change, which is always present in an organization.
|
||||
|
||||
Cultural barriers are typically more difficult to overcome than technical ones.
|
||||
|
||||
*Technical and Cultural* were described as barriers that exhibit a combination of technical and cultural elements.
|
||||
|
||||
## The Backstage Adoption Model
|
||||
|
||||
Backstage Insights looked for commonalities in the adoption path of a number of surveyed organizations. The following five-step model was found to be commonly, if not universally, descriptive of the adoption path of the organizations surveyed.
|
||||
|
||||
1. **Problem identification, definition, and alignment**: Identify the problem or problems that require a software solution like Backstage. Recruit the people necessary to pursue a solution.
|
||||
2. **Finding the right solution**: The identified participants frame the problem and search for solutions. In some cases Backstage had already been identified as a likely or potential solution.
|
||||
3. **Demo proof of concept**: Set up a limited demo to determine that: Backstage can solve the problem(s); Backstage fits with the organization's infrastructure; resources are available, with the right skill sets, to implement Backstage; Backstage provides value.
|
||||
4. **Full proof of concept**: Build out functionality and get feedback from users. Gather more rigorous metrics regarding perceived value. This stage is characterized by some hard-to-reverse implementation decisions, so due diligence is advised.
|
||||
5. **Driving full adoption**: This stage involves committing resources to full adoption. In some cases, expensive mistakes might need to be corrected, despite due diligence in step 4. Resources need to be devoted to shifting the culture to one that values and relies on Backstage.
|
||||
|
||||
### The Problem To Be Solved: A Note on Desired Outcomes
|
||||
|
||||
*Outcomes* are organizational results of adopting Backstage. Desired outcomes are ones that alleviate the problems identified in (1), above.
|
||||
|
||||
Backstage Insights surveyed both internal (Spotify) Backstage adopters and external organizations to determine the outcomes adopters hoped to achieve. The number one outcome for both internal and external users was to **maintain clear ownership of software**.
|
||||
|
||||
For external adopters, other top outcomes were consistent with *improving the maturity level of their development practices*, for example standarizing software development practices and increasing collaboration. For internal adopters, other top outcomes were goals that relied on already-mature development practices, for example improving monitoring and tracking costs. The authors hypothesized that this difference was a function of the maturity level of the Backstage implementation at the surveyed organization: already high (for Spotify, where Backstage has been used for years) or low and still developing (for other organizations).
|
||||
|
||||
## Necessity of a Champion
|
||||
|
||||
The authors of Backstage Insights were clear that implementing Backstage in an organization requires a *champion*. This champion is dedicated at least part time to evangelizing, implementing, and driving adoption of Backstage throughout the organization.
|
||||
|
||||
Champions varied in their job titles, skill sets, and "everyday" roles. However, some characteristics were common to all Backstage champions:
|
||||
- Champions were dedicated to changing the status quo to make the professional lives of developers better throughout the organization.
|
||||
- Champions believed that Backstage was the right platform for positive change.
|
||||
- Champions were typically leaders (managers or technical leads) before taking on the champion role.
|
||||
- Champions used a wide variety of technical, leadership, and interpersonal skills to drive the adoption of Backstage.
|
||||
|
||||
### Champion Job Titles
|
||||
|
||||
This is a list of job titles held by Backstage champions in surveyed organizations:
|
||||
|
||||
* DevEx Engineering Manager (2)
|
||||
* Staff Engineer
|
||||
* Software Architect
|
||||
* QA Manager
|
||||
* Technical PM
|
||||
* IT Engineering Manager
|
||||
* Engineering Manager
|
||||
* Site Reliability Engineer
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
# Backstage User Roles for Doc
|
||||
|
||||
This document provides recommendations for user roles, or personas, for Backstage. The goal here is to identify a working set of distinct user roles around which to organize the Backstage documentation.
|
||||
|
||||
The documentation should ultimately be task-oriented, with tasks organized around users and their objectives. A process for creating this type of documentation set is under development in the CDCF Tech Doc GitHub project.
|
||||
|
||||
## Summary of Proposed User Roles
|
||||
|
||||
The following table summarizes Backstage user roles proposed by the Backstage OSS community\*. The roles assume the following:
|
||||
|
||||
- An organization has software objectives that cannot be met without a centralized solution, and has resolved to commit resources to solving those problems.
|
||||
- The organization adopts Backstage, setting up a single, central Backstage server instance ("app").
|
||||
- The organization contains many development groups. These groups can be organized in any manner, but this document assumes a flat organization of small development groups.
|
||||
- "Development group" refers to any group that produces a software product manageable in Backstage, including but not limited to internal and external toolkits and APIs; components; databases; and web-based and standalone applications.
|
||||
- The organization has ties to the Backstage open source software project, specifically:
|
||||
- One or more engineers who contribute to the project.
|
||||
- Developer users who ask questions and participate in discussions, newsgroups, and other community forums.
|
||||
|
||||
\*Ultimately. This document is a work in progress to be revised by consensus.
|
||||
|
||||
| User Role | Org Level | Description |
|
||||
| --------- | --- | ----------- |
|
||||
| Champion | Organization | A combination evangelist/implementer/coordinator dedicated to driving adoption of Backstage at an organization. The champion is vital to removing barriers to developer adoption by, among other things, making the developer experience a delight and by demonstrating Backstage's value. |
|
||||
| Administrator | Organization | An IT or DevOps professional responsible for setting up and maintaining an organization's Backstage app. The administrator might or might not also be the Backstage champion. |
|
||||
| Internal Integrator | Group or Org | An engineer within an organization who creates or modifies the org's Backstage app (typically by writing or modifying a plugin) to add functionality required by the org. This modification might or might not then be contributed back to the Backstage OSS project. |
|
||||
| Group maintainer | Group | A member of a software group responsible for keeping the group's Backstage entries up to date. |
|
||||
| End-user developer | Group | The "bread and butter" user of Backstage, an end-user developer is part of a group within an organization that uses Backstage to both learn about and use software components within the org and to publish and document its own software. |
|
||||
| Contributor developer | Backstage OSS | A contributor to the Backstage open-source project. Many if not most contributors develop plugins to extend the functionality and integration capabilities of Backstage. |
|
||||
| Integrator | Backstage OSS | A contributing developer who develops a plugin that enables Backstage to interoperate with another system. |
|
||||
|
||||
These roles might overlap; or, in some cases, especially in small organizations, the same person might fill two or more roles. For example, the champion might be the Backstage administrator, and/or might also be responsible for internal integration projects. Or, an integration project might fall to an end-user developer in a group that requires functionality not yet available in Backstage.
|
||||
Loading…
Reference in New Issue