Skip to content
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

Jump to bottom

Edit the docs to reflect our new messaging #19214

Closed
3 of 4 tasks
ptgott opened this issue Dec 8, 2022 · 5 comments · Fixed by #37449
Closed
3 of 4 tasks

Edit the docs to reflect our new messaging #19214

ptgott opened this issue Dec 8, 2022 · 5 comments · Fixed by #37449
Labels
documentation

Comments

@ptgott
Copy link
Contributor

ptgott commented Dec 8, 2022 •
edited by lsgunn-teleport
Loading

Applies To

We should review every page in the docs, ideally using an automated system.

Details

We've changed some ways we talk about the product, so we should reflect these in the docs.

Terms to change

  • "Access plane" -> "Access Platform"
  • We say now "protocols" instead of describing "[A-Za-z]+ Access" as a product: "SSH", "Kubernetes", "Databases", "Windows", "Applications". The main point is that these aren't discrete sub-products, but protocols you can add as part of the Teleport Access Platform.
  • "Open Source Teleport" -> "Teleport Community Edition"
  • "Teleport Cloud" -> "Teleport Enterprise Cloud"

Automated checking

One thing that will help with this is a linter in our docs engine for incorrect usages of Teleport terms (gravitational/docs#154). We can add this linter, then introduce proscribed/prescribed terms gradually until all of the docs are compliant with the new messaging.

Short product descriptions we should add to the docs

When we describe the benefits of Teleport, we can draw from one of these:

Tagline

Identity-Native Infrastructure Access. Faster. More Secure.

~50-word description

Teleport is the first identity-native infrastructure access platform for engineers and machines. By replacing insecure secrets with true identity, Teleport delivers phishing-proof zero trust for every engineer and service connected to your global infrastructure. The open source Teleport Access Platform provides a frictionless developer experience and a single source of truth for infrastructure access.

~100-word description

Teleport is the first identity-native infrastructure access platform for engineers and machines. By replacing insecure secrets like passwords, keys and tokens with true identity based on biometrics and security modules, Teleport delivers phishing-proof zero trust for every engineer and service connected to your global infrastructure. The open-source Teleport Access Platform consolidates connectivity, authentication, authorization and audit into a single source of truth for access policy across your entire infrastructure while delivering a frictionless developer experience. Teleport replaces VPNs, shared credentials, secrets vaults and legacy PAM solutions, improving security and engineering productivity.

Related Issues
@ptgott
Copy link
Contributor Author

ptgott commented May 3, 2023

We have a messaging linter in gravitational/docs to catch incorrect term usage. You can configure it here: https://github.com/gravitational/docs/blob/main/messaging-config.json

@lsgunn-teleport lsgunn-teleport mentioned this issue Sep 28, 2023
Merged
@lsgunn-teleport
Copy link
Contributor

Search only revealed a couple of instances of "Access plane". I'm not sure Access Platform is still a thing, but if it is:
[#32769]

@lsgunn-teleport lsgunn-teleport mentioned this issue Sep 28, 2023
Merged
@lsgunn-teleport
Copy link
Contributor

There are a few stragglers that I wasn't sure about (like OSS AMIs). [#32771]

@lsgunn-teleport
Copy link
Contributor

@ptgott @xinding33 Do we really want
"Teleport Cloud" -> "Teleport Enterprise Cloud"
or
"Teleport Cloud" -> "Teleport cloud platform" (this might be easier because it's less context-sensitive)
or
"Teleport Cloud" -> "Teleport Team and Teleport Enterprise Cloud" (this might be more difficult to do globally or programmatically because it's likely to depend on context).

@ptgott
Copy link
Contributor Author

ptgott commented Oct 3, 2023

@lsgunn-teleport I think all of these changes depend on context:

Change When to use
"Teleport Cloud" -> "Teleport Enterprise Cloud" A feature is available for Teleport Enterprise Cloud but not for Team
"Teleport Cloud" -> "Teleport cloud platform" We're talking about architecture, e.g., the need to deploy the Auth Service/Proxy Service
"Teleport Cloud" -> "Teleport Team and Teleport Enterprise Cloud" I think we can pretty much always say "The Teleport cloud platform" instead of these, unless we want to be really explicit about which editions we support.

What do you think?

@ptgott ptgott mentioned this issue Feb 2, 2024
Merged
ptgott added a commit that referenced this issue Feb 2, 2024
@ptgott
Add linters for consistent docs product language
d1f415e 
Closes #19214

Maintaining a consistent language for talking about Teleport products is
important for ensuring clarity in the documentation. This change adds
rules to our Vale linting config for docs to help maintain a consistent
product language:

- **Teleport account URL examples:** Require `example.teleport.sh`
  unless the text is mentioning the status page.
- **Service names:** Require these to be capitalized.
- **Enforce consistency in other areas where we often get
  discrepancies:** e.g., "Auth Service instances" instead of "auth
  servers".

This change also renames the `messaging` style rule to
`consistent-terms` so we don't have a `messaging.messaging` rule.

Note that these linters overlap with similar ones that we run from the
`gravitational/docs` repo. The plan is to remove the latter once we
merge the linters here.
ptgott added a commit that referenced this issue Feb 6, 2024
@ptgott
Add linters for consistent docs product language
3f58815 
Closes #19214

Maintaining a consistent language for talking about Teleport products is
important for ensuring clarity in the documentation. This change adds
rules to our Vale linting config for docs to help maintain a consistent
product language:

- **Teleport account URL examples:** Require `example.teleport.sh`
  unless the text is mentioning the status page.
- **Service names:** Require these to be capitalized.
- **Enforce consistency in other areas where we often get
  discrepancies:** e.g., "Auth Service instances" instead of "auth
  servers".

This change also renames the `messaging` style rule to
`consistent-terms` so we don't have a `messaging.messaging` rule.

Note that these linters overlap with similar ones that we run from the
`gravitational/docs` repo. The plan is to remove the latter once we
merge the linters here.
ptgott added a commit that referenced this issue Feb 9, 2024
@ptgott
Add linters for consistent docs product language
8b76860 
Closes #19214

Maintaining a consistent language for talking about Teleport products is
important for ensuring clarity in the documentation. This change adds
rules to our Vale linting config for docs to help maintain a consistent
product language:

- **Teleport account URL examples:** Require `example.teleport.sh`
  unless the text is mentioning the status page.
- **Service names:** Require these to be capitalized.
- **Enforce consistency in other areas where we often get
  discrepancies:** e.g., "Auth Service instances" instead of "auth
  servers".

This change also renames the `messaging` style rule to
`consistent-terms` so we don't have a `messaging.messaging` rule.

Note that these linters overlap with similar ones that we run from the
`gravitational/docs` repo. The plan is to remove the latter once we
merge the linters here.
github-merge-queue bot pushed a commit that referenced this issue Feb 13, 2024
@ptgott
Add linters for consistent docs product language (#37449)
c1462ba 
* Add linters for consistent docs product language

Closes #19214

Maintaining a consistent language for talking about Teleport products is
important for ensuring clarity in the documentation. This change adds
rules to our Vale linting config for docs to help maintain a consistent
product language:

- **Teleport account URL examples:** Require `example.teleport.sh`
  unless the text is mentioning the status page.
- **Service names:** Require these to be capitalized.
- **Enforce consistency in other areas where we often get
  discrepancies:** e.g., "Auth Service instances" instead of "auth
  servers".

This change also renames the `messaging` style rule to
`consistent-terms` so we don't have a `messaging.messaging` rule.

Note that these linters overlap with similar ones that we run from the
`gravitational/docs` repo. The plan is to remove the latter once we
merge the linters here.

* Respond to zmb3 feedback
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add linters for consistent docs product language gravitational/teleport
2 participants
@ptgott @lsgunn-teleport