search

cockroachdb / docs

CockroachDB user documentation
https://cockroachlabs.com/docs
Creative Commons Attribution 4.0 International
190 stars 460 forks source link

--tutorial to educate users about CockroachDB in CLI #1199

Closed kuanluo closed 6 years ago

kuanluo commented 7 years ago

Our CLI currently don't offer any education on the core value props of Cockroach, and would benefit from having a few lines of texts between installation steps. Or perhaps a tutorial that users can turn on/off.

Here are a list of steps where I see as potentials of a-ha moments:

  1. After starting the first node: recommend user dump some sample data (ie: startrek).
  2. After user successfully dumped startrek data: explain Cockroach breaks down data to 64MB chunks, and they're ranges.
  3. Recommend user start two more nodes by explaining Cockroach is distributed.
  4. After 3 nodes are started in the cluster: explain ranges of data are now evenly sitting across 3 nodes. Here's a way to prove it...
  5. Recommend user kill a node to see how data survives.
  6. To conclude, point to the replication graph in the admin ui for future monitoring.

Even if users decide Cockroach is not a good fit for them after installation, they would have a basic understanding of what Cockroach is and how it is different, should an appropriate use case appear later on.

@jseldess @sploiselle @dianasaur323

dianasaur323 commented 7 years ago

@kuanluo Thanks for writing this up. Looks like a good start to me. @jseldess, Kuan and I had discussed how it might make sense to test this flow out in docs to see how it works before investing engineering time into a tutorial. Thoughts?

jseldess commented 7 years ago

@dianasaur323, I can try that. But it'd also be fun to map out the cli guidance here. I like @kuanluo's ideas. I'll add more thoughts soon.

jseldess commented 6 years ago

@piyush-singh, I'm closing this but want to put it on your radar, in case you think it's worth investing in making the cli more informative/educational.