cloud: improve one console docs for instances and My TiDB Page#22743
Closed
qiancai wants to merge 6 commits intopingcap:release-8.5from
Closed
cloud: improve one console docs for instances and My TiDB Page#22743qiancai wants to merge 6 commits intopingcap:release-8.5from
qiancai wants to merge 6 commits intopingcap:release-8.5from
Conversation
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Co-authored-by: Aolin <aolinz@outlook.com>
|
Skipping CI for Draft Pull Request. |
ti-chi-bot
bot
added
do-not-merge/work-in-progress
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
ti-chi-bot
bot
added
the
size/XXL
Collaborator
Author
|
Closing this draft because the correct source branch is pingcap:feature/preview-one-console. Replaced by #22744. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request implements a large-scale terminology update across the TiDB Cloud documentation, replacing "Cluster" with "Instance" for Starter, Essential, and Premium plans, and updating UI navigation references to the "My TiDB" page. It also introduces a new management guide for projects and resources. The review feedback identifies several opportunities to better align with the repository's style guide, including overhauling passive voice constructions into active voice, ensuring the use of present tense for system behaviors, and replacing embedded raw SVG code with descriptive text for improved maintainability.
Comment on lines
+74
to
+76
| - TiDB X instances that do not belong to any project are displayed in a table named `Out of project`. | ||
| - TiDB X instances that belong to specific projects are displayed in their corresponding TiDB X project tables. | ||
| - TiDB Cloud Dedicated clusters are displayed in their corresponding Dedicated project tables. These tables have a **D** in the folder icon to identify the **Dedicated** project type. |
Contributor
There was a problem hiding this comment.
Avoid using passive voice to describe system behavior. Active voice is more direct and easier to read.
Suggested change
| - TiDB X instances that do not belong to any project are displayed in a table named `Out of project`. | |
| - TiDB X instances that belong to specific projects are displayed in their corresponding TiDB X project tables. | |
| - TiDB Cloud Dedicated clusters are displayed in their corresponding Dedicated project tables. These tables have a **D** in the folder icon to identify the **Dedicated** project type. | |
| - TiDB Cloud displays TiDB X instances that do not belong to any project in a table named `Out of project`. | |
| - TiDB Cloud displays TiDB X instances that belong to specific projects in their corresponding TiDB X project tables. | |
| - TiDB Cloud displays TiDB Cloud Dedicated clusters in their corresponding Dedicated project tables. These tables have a **D** in the folder icon to identify the **Dedicated** project type. |
References
- Avoid passive voice overuse. (link)
| ### Create a project | ||
|
|
||
| > **Note:** | ||
| > |
Contributor
There was a problem hiding this comment.
Including raw SVG code in Markdown files makes them difficult to maintain and read. It is recommended to use descriptive text labels (e.g., Dedicated project icon) or a reusable component if available, consistent with the repository's technical writing standards.
Suggested change
| > | |
| | Project icon in the TiDB Cloud console | **Dedicated project icon** | **TiDB X project icon** | N/A | |
References
- Clarity, simplicity, completeness, and readability. (link)
Comment on lines
+99
to
+100
| - If the project is created for TiDB X instances, click **Confirm**. | ||
| - If the project is created for {{{ .dedicated }}} clusters, select the **Create for Dedicated Cluster** option, configure [Customer-Managed Encryption Keys (CMEK)](/tidb-cloud/tidb-cloud-encrypt-cmek-aws.md) and [maintenance window](/tidb-cloud/configure-maintenance-window.md) for the project, and then click **Confirm**. |
Contributor
There was a problem hiding this comment.
Avoid using passive voice in instructions. Using active voice makes the steps clearer and more direct for the user.
Suggested change
| - If the project is created for TiDB X instances, click **Confirm**. | |
| - If the project is created for {{{ .dedicated }}} clusters, select the **Create for Dedicated Cluster** option, configure [Customer-Managed Encryption Keys (CMEK)](/tidb-cloud/tidb-cloud-encrypt-cmek-aws.md) and [maintenance window](/tidb-cloud/configure-maintenance-window.md) for the project, and then click **Confirm**. | |
| - For TiDB X instances, click **Confirm**. | |
| - For {{{ .dedicated }}} clusters, select the **Create for Dedicated Cluster** option, configure [Customer-Managed Encryption Keys (CMEK)](/tidb-cloud/tidb-cloud-encrypt-cmek-aws.md) and [maintenance window](/tidb-cloud/configure-maintenance-window.md) for the project, and then click **Confirm**. |
References
- Avoid passive voice overuse. (link)
|
|
||
| To manage a project, take the following steps: | ||
|
|
||
| 1. In the TiDB Cloud console, navigate to the [**My TiDB**](https://tidbcloud.com/tidbs) page of your organization, and then click the **Project view** tab. |
Contributor
There was a problem hiding this comment.
The raw SVG code clutters the Markdown source. Please replace it with a descriptive text label or a standard icon component.
Suggested change
| 1. In the TiDB Cloud console, navigate to the [**My TiDB**](https://tidbcloud.com/tidbs) page of your organization, and then click the **Project view** tab. | |
| 1. In the TiDB Cloud console, navigate to the [**My TiDB**](https://tidbcloud.com/tidbs) page of your organization, and then click the **Project view** icon to go to the project view. |
References
- Clarity, simplicity, completeness, and readability. (link)
|
|
||
| 2. In the project view, locate your target project, and then manage it as follows: | ||
|
|
||
| - For both TiDB X and TiDB Dedicated projects, you can click **...** in the row of the target project to perform quick actions on a project, such as renaming the project or inviting members to the project. For more information, see [Manage project access](/tidb-cloud/manage-user-access.md). |
Contributor
There was a problem hiding this comment.
Avoid repeating "the project" multiple times in the same sentence. Using pronouns like "it" makes the sentence more concise.
Suggested change
| - For both TiDB X and TiDB Dedicated projects, you can click **...** in the row of the target project to perform quick actions on a project, such as renaming the project or inviting members to the project. For more information, see [Manage project access](/tidb-cloud/manage-user-access.md). | |
| - For both TiDB X and TiDB Dedicated projects, you can click **...** in the row of the target project to perform quick actions, such as renaming the project or inviting members to it. For more information, see [Manage project access](/tidb-cloud/manage-user-access.md). |
References
- Avoid unnecessary words and repetition. (link)
|
|
||
| - If you have at least one manual or automatic backup, you can see the number of backups and the charging policy for backups. Click **Continue** and enter `<organization name>/<project name>/<cluster name>`. | ||
| - If you do not have any backups, just enter `<organization name>/<project name>/<cluster name>`. | ||
| If you want to restore a deleted {{{ .essential }}} instance or {{{ .dedicated }}} cluster sometime in the future, make sure that you have a backup of it. Otherwise, you cannot restore it anymore. |
Contributor
There was a problem hiding this comment.
Avoid unnecessary words like "sometime" and "make sure". Active voice and direct instructions are preferred.
Suggested change
| If you want to restore a deleted {{{ .essential }}} instance or {{{ .dedicated }}} cluster sometime in the future, make sure that you have a backup of it. Otherwise, you cannot restore it anymore. | |
| If you want to restore a deleted {{{ .essential }}} instance or {{{ .dedicated }}} cluster in the future, ensure you have a backup of it. Otherwise, you cannot restore it. |
References
- Avoid unnecessary words and repetition. (link)
|
|
||
| Once a backed up TiDB Cloud Dedicated cluster is deleted, the existing backup files of the cluster are moved to the recycle bin. | ||
| Once a backed up {{{ .essential }}} instance or TiDB Cloud Dedicated cluster is deleted, the existing backup files of it are moved to the Recycle Bin. | ||
|
|
Contributor
There was a problem hiding this comment.
Avoid passive voice to make the documentation more engaging and clearer.
Suggested change
| When you delete a backed-up {{{ .essential }}} instance or TiDB Cloud Dedicated cluster, TiDB Cloud moves its existing backup files to the Recycle Bin. |
References
- Avoid passive voice overuse. (link)
| ## How the SQL proxy account is created | ||
|
|
||
| The SQL proxy account is automatically created during TiDB Cloud cluster initialization for the TiDB Cloud user who is granted a role with permissions in the cluster. | ||
| The SQL proxy account is automatically created during initialization of a {{{ .starter }}} instance or {{{ .dedicated }}} cluster for the TiDB Cloud user who is granted a role with permissions in the instance or cluster. |
Contributor
There was a problem hiding this comment.
Using active voice improves the clarity of the instruction.
Suggested change
| The SQL proxy account is automatically created during initialization of a {{{ .starter }}} instance or {{{ .dedicated }}} cluster for the TiDB Cloud user who is granted a role with permissions in the instance or cluster. | |
| TiDB Cloud automatically creates the SQL proxy account during initialization of a {{{ .starter }}} instance or {{{ .dedicated }}} cluster for the TiDB Cloud user who is granted a role with permissions in the instance or cluster. |
References
- Avoid passive voice overuse. (link)
| 5. Click **Create** to create a {{{ .starter }}} instance. | ||
|
|
||
| Your TiDB Cloud cluster will be created in approximately 30 seconds. | ||
| Your {{{ .starter }}} instance will be created in approximately 30 seconds. |
Contributor
There was a problem hiding this comment.
Prefer present tense and active voice for a more direct user experience.
Suggested change
| Your {{{ .starter }}} instance will be created in approximately 30 seconds. | |
| TiDB Cloud creates your {{{ .starter }}} instance in approximately 30 seconds. |
References
- Prefer present tense unless describing historical behavior. Avoid passive voice overuse. (link)
| A Request Unit (RU) is a unit of measure used to represent the amount of resources consumed by a single request to the database. The amount of RUs consumed by a request depends on various factors, such as the operation type or the amount of data being retrieved or modified. | ||
|
|
||
| Once a cluster reaches its usage quota, it immediately denies any new connection attempts until you [increase the quota](/tidb-cloud/manage-serverless-spend-limit.md#update-spending-limit) or the usage is reset upon the start of a new month. Existing connections established before reaching the quota will remain active but will experience throttling. For example, when the row-based storage of a cluster exceeds 5 GiB for a free cluster, the cluster automatically restricts any new connection attempts. | ||
| Once a {{{ .starter }}} instance reaches its usage quota, it immediately denies any new connection attempts until you [increase the quota](/tidb-cloud/manage-serverless-spend-limit.md#update-spending-limit) or the usage is reset upon the start of a new month. Existing connections established before reaching the quota will remain active but will experience throttling. For example, when the row-based storage of a {{{ .starter }}} instance exceeds 5 GiB for a free {{{ .starter }}} instance, the instance automatically restricts any new connection attempts. |
Contributor
There was a problem hiding this comment.
Use present tense for describing current system behavior.
Suggested change
| Once a {{{ .starter }}} instance reaches its usage quota, it immediately denies any new connection attempts until you [increase the quota](/tidb-cloud/manage-serverless-spend-limit.md#update-spending-limit) or the usage is reset upon the start of a new month. Existing connections established before reaching the quota will remain active but will experience throttling. For example, when the row-based storage of a {{{ .starter }}} instance exceeds 5 GiB for a free {{{ .starter }}} instance, the instance automatically restricts any new connection attempts. | |
| Once a {{{ .starter }}} instance reaches its usage quota, it immediately denies any new connection attempts until you [increase the quota](/tidb-cloud/manage-serverless-spend-limit.md#update-spending-limit) or the usage is reset at the start of a new month. Existing connections established before reaching the quota remain active but experience throttling. |
References
- Prefer present tense unless describing historical behavior. (link)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What is changed, added or deleted? (Required)
This PR improves the TiDB Cloud one console documentation for the
release-8.5branch.instancewhere the UI now shows instance-level conceptsWhich TiDB version(s) do your changes apply to? (Required)
What is the related PR or file link(s)?
Do your changes match any of the following descriptions?
Validation
./scripts/verify-links.sh./scripts/verify-link-anchors.shnode ./scripts/verify-internal-links-in-toc.js