What's New and Improved in TiDB Docs

2020-08-13Lilian LeeEngineering

A distributed SQL database's documentation

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:

New entries for each documentation set

New entries for each documentation set

The following table shows how the documentation is organized:

Product/ProjectTop level pageSub-level page
TiDB databaseTiDB docsTiDB is a MySQL-compatible, NewSQL database that features horizontal scalability, strong consistency, and high availability. You can deploy TiDB on-premise or in-cloud.
ToolsTools docsTiDB Operator docs
TiDB 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 CloudTiDB Cloud docsTiDB 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 improvementExample/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.

A cloud-native database's doc search results

Accurate, version-specific search results

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:

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:

Documentation

Ready to get started with TiDB?