Rewrite top-level docs page with "super" naming #5336
Conversation
philrz
changed the title
| Compared to putting JSON data in a relational column, the | ||
| [super-structured data model](formats/zed.md) makes it really easy to | ||
| mash up JSON with your relational tables. The `super` command is a little | ||
| like [DuckDB](https://duckdb.org/) and a little like | ||
| [`jq`](https://stedolan.github.io/jq/) but super-structured data ties the | ||
| two patterns together with strong typing of dynamic values. |
There was a problem hiding this comment.
This was some new content proposed by @mccanne when he responded on Slack after seeing an early draft. Indeed, even as I was doing the first pass I knew we'd need to move beyond just the jq comparison, but I didn't have the confidence to start launching into SQL-centric content on my own, so happy to include this!
| While `super` and its accompanying data formats are production quality, the project's | ||
| [SuperDB data lake](commands/zed.md) is a bit [earlier in development](commands/zed.md#status). |
There was a problem hiding this comment.
I intentionally moved this paragraph to the bottom of this section. One of my challenges in this rewrite was the contrast between SuperDB-the-project (which covers everything production quality that's available right now) and "SuperDB data lake" / super db-the-command (which we've acknowledged will be de-emphasized in the short term... but they still invoke the words "super db"). So I want to avoid sending mixed message.
While I would not advocate amputating lake coverage from the docs (especially since we have users relying on it in production!) I'm sensing that moving lake materials to less prominent places may help reduce confusion among new readers.
| * The [super data model](formats/zed.md) is the abstract definition of the data types and semantics | ||
| that underlie the super-structured data formats. | ||
| * The [super data formats](formats/README.md) are a family of |
There was a problem hiding this comment.
In a first iteration I had these as "super-structured data model" and "super-structured data formats", but I recognized it was a lot of words and could get unwieldy considering how often we mention the data model in the docs. @mccanne was in favor of dropping the "-structured" and keeping it lowercase "s". We agreed that saying "SuperDB" in this spot would feel odd, and "Super" with a capital "S" is not something we're attempting anywhere else, so "super" basically wins by default at that point.
| All of its examples use `super db` commands run on the command line. | ||
| Run `super db -h` or `-h` with any subcommand for a list of command options | ||
| and online help. The same language query that works for `super` operating | ||
| on local files or streams also works for `super db query` operating on a lake. | ||
|
|
||
| ## Design Philosophy |
There was a problem hiding this comment.
This whole paragraph basically helps justify the lake and therefore should perhaps move or be dropped entirely, but I intentionally did not attempt that in this pass.
A rendered draft is staged at https://spiffy-gnome-8f2834.netlify.app/docs/next
Goals in renaming as affects docs
We know we want to:
What I'm attempting here
This is a small step in the overall renaming effort to try out the new "super"-centric names.
We know the renaming is not a simple search-and-replace of "zed" with "super", so I wanted to confirm that the current proposed from/to list feels ok when applied to the existing materials. I've started with a rewrite of the first page users see when they land at https://zed.brimdata.io/docs/next
I've done some minimal reworking of sentence structure and moving paragraphs around where it felt necessary, but I've kept the overall content intact.
If this passes muster my hope is that we can begin re-using the new terms in similar ways as we attack more docs pages, READMEs in the repos, web site content, etc.
What I'm not attempting (yet)
In this pass I'm intentionally not trying to:
...though I fully expect these things will happen in subsequent passes.