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:

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:

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!