Background

We are excited to announce the launch of our documentation site. The goal of Dolt and DoltHub is to enable developers and the data community with radically better data infrastructure. High quality documentation should empower users by allowing them to see how Dolt and DoltHub can fit within their existing workflows.

Sections

In writing our documentation we decided to step a level above API documentation. Our command line interface (CLI) is documented on GitHub. What we felt was missing was documentation showing users how Dolt and DoltHub work in practice. Applying version control primitives to data management requires detailed examples, as in many cases it requires thinking what a database can do quite differently. Thus we put together a series of practical guides that use real public data. You can walk through each of these by installing Dolt by running the following command:

sudo curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | sudo bash

and then following along.

Next, we briefly describe the motivations and goals for each section.

Getting Started

The Getting Started guide walks users through getting up and running with DoltHub. The aim is to get users going as quickly as possible.

Cookbook

Existing RDBMS solutions can be thought of as blackboxes that expose SQL as a query interface where the conflict semantics are essentially "last write wins". State is simple. That's a good thing for optimizing for read and write speed. This makes sense, the original motivation RDBMS solutions was as application backing stores, and they do that well.

Dolt offers a familiar declarative query interface, i.e. SQL, but radically different conflict semantics. Branches and commits underpin these unique semantics. The goal is to allow users to describe their data in a familiar way, but offer them a whole new set of capabilities to address use-cases centered on the massively increasing use of data. RDBMS are often used in a context they were not designed for, necessitating writing a lot of application code. Think of implementing pull requests in the application layer. Dolt elevates these considerations to first class concerns.

Thus the cookbook section shows how to use Dolt to do familiar things, such as acquire, subscribe, suggest changes, and hygienically manage, data. All of these activities are simple to describe, but hard to do with existing tools. What's exciting about this section is the user has to write almost no code to access a powerful set of capabilities.

Use Cases

The final section goes deeper on the various use-cases where we think Dolt and DoltHub can create value. We dig into specific examples, and offer code snippets to illustrate the skeleton of a solution. Just like the cookbook section, what's exciting is how little code one actually needs to write.

Next Up

We have many improvements planned for the near future:

1. API documentation for our command line interface, already on GitHub but coming to our docs site soon
2. SQL documentation to describe our implementation, which as we saw in this post has some unique aspects covering version control
3. More use-cases

Conclusion

We believe that Dolt and DoltHub fill a fundamental hole in the database and data tools market. For Dolt and DoltHub to fill that gap, they must be widely adopted and loved by the developer and data community. As such, we will continue to invest in our documentation with the goal of making it as easy as possible to get value from Dolt and DoltHub.