Set expectations in README and first docs pages #5665
Conversation
| SuperDB can also run on a | ||
| [super-structured data lake](https://superdb.org/docs/commands/super-db/#the-lake-model) | ||
| using the `super db` sub-commands. | ||
|
|
||
| ## Project Status |
There was a problem hiding this comment.
I moved the Project Status section above the Try It section since I figured it was good to draw their attention first to the project's early status.
| @@ -29,7 +44,7 @@ packaged up in the easy-to-understand | |||
| [Super JSON data format](formats/jsup.md) and | |||
| [SuperSQL language](language/_index.md). | |||
|
|
|||
| While `super` and its accompanying data formats are production quality, the project's | |||
| While `super` and its accompanying data formats are production quality for some use cases, the project's | |||
There was a problem hiding this comment.
I figured saying a flat "production quality" clashed with our message of "expect speedbumps". Those of us who work on it know that years of real world usage of zq has made super in its current form quite solid for many production use cases, e.g., things for which one might otherwise reach for jq. But that history will not be obvious to a new SQL-centric user, so I figured we could just tone down the language a tad.
| ## Binary Download | ||
|
|
||
| We offer pre-built binaries for macOS, Windows and Linux for both amd64/x86 and arm | ||
| architectures in the super [GitHub Release page](https://github.com/brimdata/super/releases). | ||
|
|
||
| Once the `super` binary is unpacked from a downloaded package, run a [quick test](#quick-tests). | ||
|
|
There was a problem hiding this comment.
Since the plan is to hide the Releases link from the repo's front page to reflect that there's not yet GA SuperDB releases, it seems we should drop it here as well. Legacy Zed users will hopefully find their way to the older releases via https://www.brimdata.io and https://www.brimdata.io/download .
| ## Building From Source | ||
|
|
||
| If you have Go installed, you can easily build `super` from source: | ||
|
|
||
| ```bash | ||
| go install github.com/brimdata/super/cmd/super@latest | ||
| go install github.com/brimdata/super/cmd/super@main |
There was a problem hiding this comment.
@latest would still get them the last GA Zed v1.18.0 release, which is not what we want. Since the README/docs changes in this PR set expectations that they're installing code that's still under development, tip-of-main is exactly what we want them to do for now.
As @mccanne has plans to start introducing some new audiences to SuperDB, we want to be careful in setting expectations, since those users may arrive at the project README and/or docs pages ready to tinker and we want their first impressions to be in line with the project's status. To that end, the changes in this branch adjust the tone of the README and some of the first docs pages from something like "come 'n' get it!" to something more like "try it... expect some speedbumps... we welcome your feedback".
You can see the rendered version of the key part of the README here, and the rendered change in one of the docs pages looks like the bottom box shown in this screenshot:
Once we've got consensus on the language used here or some adjusted variation, I plan to do two immediate follow-on changes:
I'd put up a PR to propose some similar adjustments in the https://superdb.org front page, as that also has a bit of "come 'n' get it!" tone at the moment.
I'd hide the Releases area circled in red in the following screenshot, since (in line with the text) we're not yet offering GA releases of SuperDB, and we don't want to confuse new users if they should stumble across the releases from the older "Zed" project from which SuperDB evolved in this same repo. We have many legacy users that still use Zed and there's links to the releases from blog articles and other web sites, and hiding that Releases area does not disable the actual https://github.com/brimdata/super/releases page or release artifacts if the user happens to access them by URL. Indeed, at the moment we still mention the availability of the older Zed releases at https://www.brimdata.io and this approach allows the links to the various artifacts from the Download page to remain active. Perhaps at some point we may choose to separate from all history of the Zed project to eliminate any possible confusion among the new SuperDB user base. However, as we intend to help those users transition to SuperDB if possible, I believe we have consensus on the "hide" approach for now.