Skip to content

[chore] Fix link fragments #293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chalin merged 1 commit into from
Feb 25, 2025
Merged

[chore] Fix link fragments #293

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions .markdown-link-check.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,6 @@
{
"pattern": "^http://localhost"
},
{
"pattern": "^#"
},
{
"pattern": "^https://(www|docs).tremor.rs"
},
Expand Down
22 changes: 9 additions & 13 deletions analyses/0008-backstage/backstage-analysis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ tags: backstage
created: 2023-09-01
modified: 2023-11-28
author: Dave Welsch (@dwelsch-esi)
cSpell:ignore: clotributor dwelsch Welsch runbooks WCAG
---

# Introduction
Expand Down Expand Up @@ -95,7 +96,7 @@ to their area of concern:

- [Project documentation][proj-doc]
- [Contributor documentation][contributor-doc]
- [Website and documentation infrrastructure][website]
- [Website and documentation infrastructure][website]

Examples of CNCF documentation that demonstrates the analysis criteria are
linked from the [Criteria][cncf-doc-criteria] specification.
Expand Down Expand Up @@ -277,10 +278,10 @@ 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.
over to [Implementation][implementation-doc]. 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

Expand Down Expand Up @@ -405,7 +406,7 @@ There is an active [Discussions][backstage-discussion] board in the GitHub repo.
page][backstage-github-community] on GitHub. Help resources are not linked from
the Getting Started documentation.

Backstage is listed in the [Clotributor][clotributor] tool.
Backstage is listed in the [Clotributor][] tool.

### Project governance documentation

Expand All @@ -416,8 +417,7 @@ Governance is clearly documented in [GOVERNANCE.md][backstage-governance].
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].
from the product documentation.

# Website

Expand Down Expand Up @@ -577,14 +577,12 @@ 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/blob/master/CONTRIBUTING.md
[backstage-demo]:
https://demo.backstage.io/catalog?filters%5Bkind%5D=component&filters%5Buser%5D=owned
https://demo.backstage.io/catalog?no-link-check&filters%5Bkind%5D=component&filters%5Buser%5D=owned
[backstage-discussion]: https://discord.gg/backstage-687207715902193673
[backstage-doc-contrib]:
https://backstage.io/docs/contribute/getting-involved#write-documentation-or-improve-the-website
Expand Down Expand Up @@ -628,8 +626,6 @@ Improve compliance in these areas:
[contrib-doc-rec]: #recommendations-contributor-documentation
[contributor-doc]: #contributor-documentation
[doc-survey]: backstage-doc-survey.csv
[implementation]: #implementation
[info-arch-recommend]: #recommendations
[proj-doc-comments]: #comments-project-documentation
[proj-doc-rec]: #recommendations-project-documentation
[proj-doc]: #project-documentation
Expand Down
24 changes: 12 additions & 12 deletions analyses/0008-backstage/backstage-glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
## API

In the Backstage [Catalog](#catalog), an API is an [entity](#entity)
representing a boundary between two [compnents](#component).
representing a boundary between two [components](#component).

https://backstage.io/docs/features/software-catalog/system-model

Expand Down Expand Up @@ -41,7 +41,7 @@ declarative APIs exemplify this approach."
## Cloud Native Computing Foundation

A foundation dedicated to the promotion and advancement of
[Cloud Native Computing](#Cloud-Native-Computing). The mission of the Cloud
[Cloud Native Computing](#cloud-native-computing). The mission of the Cloud
Native Computing Foundation (CNCF) is "to make cloud native computing
ubiquitous"
([CNCF Charter](https://github.com/cncf/foundation/blob/main/charter.md)).
Expand Down Expand Up @@ -91,7 +91,7 @@ https://backstage.io/docs/features/software-catalog/system-model
## Entity

What is cataloged in the Backstage Software Catalog. An entity is identified by
[kind](#Kind), [namespace](#Namespace), and name.
[kind](#kind), [namespace](#namespace), and name.

## Evaluator

Expand All @@ -106,7 +106,7 @@ with another software system. A [user role](#user-role).

## Kind

Classification of an [entity](#Entity) in the Backstage Software Catalog, for
Classification of an [entity](#entity) in the Backstage Software Catalog, for
example _service_, _database_, and _team_.

## Kubernetes Plugin
Expand All @@ -126,7 +126,7 @@ organize [entities](#entity).

## Objective

A high level goal of a [user role](#User-Role) interacting with Backstage. Some
A high level goal of a [user role](#user-role) interacting with Backstage. Some
goals of the _administrator_ user role, for example, are to maintain an instance
("app") of Backstage; to add and update functionality via plugins; and to
troubleshoot issues.
Expand All @@ -147,8 +147,8 @@ the core features, are implemented as plugins.
## Procedure

A set of actions that accomplish a goal, usually as part of a
[use case](#Use-Case). A procedure can be high-level, containing other
procedures, or can be as simple as a single [task](#Task).
[use case](#use-case). A procedure can be high-level, containing other
procedures, or can be as simple as a single [task](#task).

## Resource

Expand All @@ -160,13 +160,13 @@ https://backstage.io/docs/features/software-catalog/system-model

## Role

See [User Role](#User-Role).
See [User Role](#user-role).

## Search

A Backstage plugin that provides a framework for searching a Backstage
[app](#app), including the [Software Catalog](#Software-Catalog) and
[TechDocs](#TechDocs). One of the core features of Backstage.
[app](#app), including the [Software Catalog](#software-catalog) and
[TechDocs](#techdocs). One of the core features of Backstage.

## Software Catalog

Expand All @@ -190,7 +190,7 @@ https://backstage.io/docs/features/software-catalog/system-model

## Task

A low-level step-by-step [Procedure](#Procedure).
A low-level step-by-step [Procedure](#procedure).

## TechDocs

Expand All @@ -200,7 +200,7 @@ Backstage.

## Use Case

A purpose for which a [user role](#User-Role) interacts with Backstage. Related
A purpose for which a [user role](#user-role) interacts with Backstage. Related
to [Objective](#objective): An objective is _what_ the user wants to do; a use
case is _how_ the user does it.

Expand Down
9 changes: 5 additions & 4 deletions analyses/0008-backstage/backstage-implementation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
---
title: Implementing Backstage Doc Improvements
tags: backstage
cSpell:ignore: rigeur runbooks toolkits
---

# Introduction

This document provides actionable suggestions for improving the Backstage
technical documentaiton.
technical documentation.

For an analysis and general discussion of recommendations on Backstage technical
documentation, see [backstage-analysis.md][backstage-analysis]].
Expand Down Expand Up @@ -142,7 +143,7 @@ The following artifacts should be written and made findable for administrators.
- 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
- Upgrade and downgrade the Backstage release version
- Troubleshoot common problems
- Tune server performance

Expand All @@ -153,7 +154,7 @@ The following artifacts should 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. Download 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:
Expand All @@ -173,7 +174,7 @@ 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
2. Where possible, using the existing 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
Expand Down
8 changes: 6 additions & 2 deletions analyses/0008-backstage/backstage-insights-summary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
cSpell:ignore: flipside
---

# Backstage Insights

This document briefly summarizes the research, branded "Backstage Insight," done
Expand All @@ -21,7 +25,7 @@ Adoption here means:
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.
truth" about all software development within the organization.

### Barriers to Adoption

Expand Down Expand Up @@ -85,7 +89,7 @@ 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
maturity level of their development practices_, for example standardizing
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
Expand Down
6 changes: 3 additions & 3 deletions analyses/0010-etcd/etcd-issues.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ including:

- _Evaluator_: Someone trying to determine whether etcd is appropriate for their
product, project, or organization.
- _Admin or Operator_: Someonereponsible for setting up and maintaining a
- _Admin or Operator_: Someone responsible for setting up and maintaining a
standalone (non-Kubernetes-backstore) production etcd service.
- _Kubernetes Admin_: Someone responsible for a Kubernetes cluster using etcd as
a backstore.
Expand Down Expand Up @@ -265,7 +265,7 @@ Sections to be added to the table of contents.
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Reference | A library of reference documents: APIs, CLIs, configuration options, and anything else a user might need to look up to complete a task. |
| Troubleshooting | A list of procedures for diagnosing and fixing problems. |
| Release Notes | The cumulative release notes for the major and minor release. See [Release Notes](#add-release-notes-to-new-releases). |
| Release Notes | The cumulative release notes for the major and minor release. |

### Remove pages

Expand All @@ -279,7 +279,7 @@ that page is listed as "Redundant with". Page URLs are relative to
| -------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------- | ----------------------------------------------------------------------------- |
| demo/ | | op-guide/authentication/authentication/ | Remove |
| dev-internal/discovery_protocol/ | op-guide/clustering/ | dev-guide/discovery_protocol/ | Remove |
| /dev-guide/interacting_v3/ | dev-guide/local_cluster/ | tutorials/\*.md | Consolidate under "Tasks". See [Tutorials](#tutorials) |
| /dev-guide/interacting_v3/ | dev-guide/local_cluster/ | tutorials/\*.md | [Consolidate under "Tasks"](#issue-convert-tutorials-to-tasks) |
| op-guide/recovery/ | op-guide/failures/, op-guide/runtime-configuration/, op-guide/runtime-reconf-design/ | | Incorporate into Troubleshooting guide |
| op-guide/data_corruption/ | op-guide/monitoring/ | | Incorporate into Troubleshooting guide |
| upgrades/ | | | Remove or archive old upgrade paths if they're no longer needed or supported. |
Expand Down
13 changes: 7 additions & 6 deletions analyses/0011-keda/keda-analysis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
---
title: KEDA Documentation Analysis
tags: kdeda
created: 2024-02-23
modified: 2024-04-09
author: Dave Welsch (@dwelsch-esi)
cSpell:ignore: Welsch dwelsch pastable
cSpell:ignore: Welsch dwelsch pastable servicedesk
---

# Introduction
Expand Down Expand Up @@ -383,9 +382,9 @@ KEDA is a **graduated** project of CNCF. This means that the project should have
### Single-source requirement

Source files for all website pages reside in a **single repo**. However, some
user documentation pages (speciifically, "Getting started" topics linked from
the main (kedacore/keda) repo) would better serve users if they were moved to
the tech docs on the website.
user documentation pages (specifically, "Getting started" topics linked from the
main (kedacore/keda) repo) would better serve users if they were moved to the
tech docs on the website.

Website files are all in the website repo.

Expand All @@ -403,7 +402,7 @@ sandbox, incubating, graduated and archived.
| Maturity | Requirement | Met? |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| Sandbox | Majority of [Website guidelines](../../docs/website-guidelines-checklist.md) satisfied | Yes |
| Sandbox | [Docs assessment](../../docs/analysis/howto.md) [cncf-servicedesk] completed. | Yes |
| Sandbox | [Docs assessment](../../docs/analysis/howto.md) [CNCF-servicedesk] completed. | Yes |
| Sandbox | **Project documentation** exists – somewhere. It is acceptable at this maturity level to link out to documentation that hasn't yet been integrated into the website. (May still be in the project GitHub repo, for example.) | Yes |
| Incubating | All [Website guidelines](../../docs/analysis/criteria.md#website) satisfied | Yes |
| Incubating | Request docs (re-)assessment through CNCF [service desk](https://servicedesk.cncf.io/) | Yes |
Expand Down Expand Up @@ -538,3 +537,5 @@ Explicitly list and solicit maintainers and contributors for documentation.
No recommendations.

<!--- References --->

[CNCF-servicedesk]: https://servicedesk.cncf.io
Loading