What’s New and Improved in TiDB Docs

Author: Lilian Lee (Content Strategist at PingCAP)

Editor: Tom Dewan

TiDB is an open-source, distributed SQL database that supports Hybrid Transactional/ Analytical Processing (HTAP) workloads. Along with the rapid releases of TiDB products and projects, we also continually improve our TiDB documentation because developer experience and user experience matter! To help with your TiDB journey, this post covers recent big changes, new content, and improvements in TiDB documentation.

Big changes

First, let’s take a look at the big changes made to TiDB documentation. These improvements include a new subdomain, an optimized doc structure, and a robust search feature.

Migrating to a new subdomain

Previously, TiDB documentation was displayed at https://pingcap.com/docs. (If you click the link now, you’re automatically redirected to a new URL.) Since June 22, 2020, all the TiDB documentation has been migrated to the docs.pingcap.com subdomain, and its new URL is https://docs.pingcap.com.

A separate subdomain name for TiDB documentation makes it much easier for you to quickly find the information you need from multiple sets of TiDB-related documentation.

Generally, we maintain a separate set of documentation for a product (or tool or component) that has its own release, the version number of which differs from that of the TiDB project. In the upper left of each documentation page, you’ll see a drop-down list that lets you select the version number you’re interested in.

Reorganizing the documentation

We’ve reorganized our documentation to make it more usable and more friendly. This reorganization includes two parts: we now provide a separate link to each documentation set to give you quicker access, and we’ve restructured the content of documents to help you find them easier with better logic.

Providing a separate entry for each documentation set

The new documentation subdomain displays an entry for each documentation set:

The following table shows how the documentation is organized:

Product/Project	Top level page	Sub-level page
TiDB database	TiDB docs	TiDB is a MySQL-compatible, NewSQL database that features horizontal scalability, strong consistency, and high availability. You can deploy TiDB on-premise or in-cloud.
Tools	Tools docs	TiDB Operator docsTiDB Operator helps manage cloud-native TiDB on Kubernetes and automates operating tasks. This makes TiDB easier to deploy on any cloud that provides managed Kubernetes. TiDB Data Migration docs TiDB Data Migration (DM) is an integrated data replication task management platform that supports full data migration and incremental data migration from MySQL or MariaDB to TiDB. It can help reduce operating costs and simplify troubleshooting. TiDB Database Tools docs TiDB database tools are a collection of useful toolkits for migrating data to or from TiDB, including Dumpling, Mydumper, Loader, Syncer, sync-diff-inspector, Backup & Restore (BR), TiDB Lightning, and TiCDC. TiUP docs TiUP is a package manager that manages components in the TiDB ecosystem, such as TiDB, TiKV, and Placement Driver (PD). You can run any component with only a single TiUP command, which makes it far easier to manage.
TiDB Cloud	TiDB Cloud docs	TiDB Cloud (Beta), the fully-managed TiDB service, is the easiest, most economical, and most resilient way to unlock the full power of TiDB in the cloud, allowing you to deploy and run TiDB clusters with just a few clicks.

Restructuring the content for each documentation set

We restructured our documentation by:

• Creating a different table of contents
• Adding more topics
• Splitting original content
• Updating or deleting outdated content

We didn’t restructure all versions of the documentation, but only the following products (and projects) and versions:

• TiDB docs: dev (the latest development version) & v4.0
• TiDB Operator docs: dev & v1.1
• TiDB Data Migration docs: dev

Earlier documentation versions retain their current structure.

Adopting a flat directory structure

If you contribute to TiDB documentation or you’re a member of TiDB Docs SIG, you probably have found that we’ve adopted a flat directory structure for all the active branches in our docs repositories (docs, docs-cn, docs-tidb-operator, docs-dm).

Previously, the directory structure was deep, with paths such as /how-to/configure/time-zone.md. Now, the equivalent path is /configure-time-zone.md, with the documentation directly in the root directory of a branch. However, we still keep some folders for relatively independent modules in the root directory, such as sql-statements, tiup, and tiflash. This way, engineers or technical writers can easily find and maintain the corresponding files, and the files won’t be overly scattered.

This change makes it much more friendly for possible future changes to the content organization. Now you can move one file to another directory or another place in the table of contents (TOC.md), without affecting the usability of the original URL. As long as you don’t modify the file name, you don’t need to worry about redirecting the original URL to a new one, because the URL doesn’t change.

You might be wondering, “If I move a file from directory A to directory B, why doesn’t the URL change?” The reason is we cut the directory section from the URL by default, and we only kept the file name section. For example, the /tiflash/tiflash-overview.md file in the docs master branch is parsed to https://docs.pingcap.com/tidb/dev/tiflash-overview.

Showing accurate, version-specific search results

To search TiDB documentation, you can use either Google Search or the embedded search box in the upper right corner of every TiDB docs page.

Last June, we made great improvements to documentation search so you can find answers much more quickly. Here are the major changes:

Major improvement	Example/Description
You can use quotes to search for an exact phrase.	Enter “CREATE VIEW” or “create view” to get the exact results with this phrase.
You can select a specific documentation set to get better results.	When you visit https://docs.pingcap.com, the TiDB docs page is displayed by default. If you want to search other doc sets such as TiDB Operator, first click Tools on the top menu bar and select TiDB Operator.
You can specify the exact version that you want to get results from.	Search results for the latest “stable” version are returned by default, but you can select your version in the drop-down list in the upper left of the page.For example, if you use TiDB Operator v1.0 and want to know how to modify the time zone setting for a TiDB cluster in Kubernetes, click Tools > TiDB Operator, select v1.0 in the drop-down, and then enter “time zone” to search.

New docs

Now you’re familiar with how the new TiDB doc site works, let’s see how to quickly find the documentation for TiDB 4.0‘s new features and TiDB Cloud beta released in June.

TiDB 4.0 feature docs

Along with the TiDB 4.0 GA release, we’ve added a lot of new 4.0 topics and updated many existing topics to help you easily use TiDB 4.0, an elastic, cloud-native, real-time HTAP database. Here are some of the 4.0 documentation highlights:

• TiUP is a new package manager that streamlines installing, configuring, and managing a TiDB cluster into a few easy commands. Quick Start Guide for the TiDB Database Platform describes how to try out TiDB in a few minutes, even in only one minute. Deploy a TiDB Cluster Using TiUP describes how to deploy TiDB clusters in the production environment.
• TiFlash is a key component that makes TiDB essentially a Hybrid Transactional/Analytical Processing (HTAP) database. TiFlash Overview describes its architecture and key features, and includes links about how to deploy a new cluster with TiFlash nodes, how to add a TiFlash node in a deployed cluster, and how to use TiFlash.
• Backup & Restore (BR) is a distributed backup and restore tool that offers high backup and restore speeds for the TiDB cluster data. BR Use Cases describes its four use cases. Use BR to Back up and Restore Data describes the BR command line, usage examples, best practices, restrictions, and implementation principles.
• TiDB Dashboard (experimental) is a Web UI for monitoring, diagnosing, and managing the TiDB cluster, which makes it much easier to troubleshoot cluster problems. TiDB Dashboard Introduction describes its main features. Key Visualizer lets you observe your read and write volume over time so that you can quickly diagnose whether the system has read or write hotspots. SQL statement analysis lets you quickly know which SQL statement is using too many system resources.
• TiCDC (experimental) is an incremental replication tool that directly subscribes to TiDB’s data changes and replicates data at the second or even the millisecond level. TiCDC Overview describes its architecture, replication features, and restrictions. You can learn how to deploy a TiCDC cluster, and how to manage your TiCDC cluster and replication tasks.

For more feature and documentation details, see What’s New in TiDB 4.0 and earlier versions of our v4.0 Release Notes.

TiDB Cloud docs

TiDB Cloud is a fully-managed Database-as-a-Service (DBaaS) product that brings everything great about TiDB to your cloud, and lets you focus on your applications, not the complexities of your database. In June, we released a complete set of TiDB Cloud documentation. Check out TiDB Cloud Documentation and start your free trial now!

What’s next

To offer you a better experience on your TiDB journey, we’ll keep updating all the documentation (docs, docs-cn, docs-tidb-operator, docs-dm). And you’re welcome to contribute through any of the following ways:

• Create GitHub issues to request changes, report errors, or ask uncovered questions.
• Create GitHub pull requests (PRs) to directly update the documentation content. Once your PR is merged, you’ll become a contributor to the Docs SIG of the TiDB Community!
• Join TiDB Community’s #sig-docs Slack channel to ask or answer questions and talk with more contributors!