-
Notifications
You must be signed in to change notification settings - Fork 129
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update docs for Zui name change & Docusaurus #2531
Conversation
docs/README.md
Outdated
* the [command-line tools](https://zed.brimdata.io/docs/commands) that work alongside Zui, and | ||
* the [Zed data formats](https://zed.brimdata.io/docs/formats). | ||
|
||
:::tip pcap processing |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this callout should be at the bottom of the page. It might be jarring for a first time user to see the words "zeek", "suricata" and "pcaps" so soon. They might think Zui is not relevant to them.
But if were at the bottom after the info on the name change, it would seem appropriate.
--- | ||
sidebar_position: 2 | ||
--- | ||
|
||
# Troubleshooting |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this section should be called "Common Problems". I'd be more included to click that than the title "Troubleshooting". That could be just me though.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, if it would not offend, I'm inclined to keep it as "Troubleshooting". I played around with changing it but as I started to look at where other docs were linking to it, it didn't feel right.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Two small changes then this looks great to me.
These changes give the wiki a much-needed overhaul. This includes:
There's a companion draft PR brimdata/zui-docs-site#1 to handle the Docusaurus build & deployment to Netlify. As long as this PR is up you can assume that any commits I've made here will be reflected in https://zui.brimdata.io/docs. I've added a CNAME in our DNS config pointing
zui.brimdata.io
at the new Netlify site, but none of our other materials are yet linking tozui.brimdata.io
, so it's effectively a staging site for now.Since I know a lot of folks weren't super familiar with the Brim wiki content, rather than doing a diff-centric review of the old vs. new content, you might want to just review the new site at https://zui.brimdata.io/docs with fresh eyes as if we were starting the docs from scratch. As you can imagine, I'm not trying to exhaustively document everything new/awesome about Zui. I'm just trying to make the content we already have relevant, accurate, and attractive. Once Zui is out I certainly look forward to adding more materials!
Here's a summary of some notable content changes you'll find here.
I dropped the concept of "cookbooks". At one time there were a few experimental things we wanted to expose while they were still somewhat half-baked and that's what I'd documented in cookbooks. But over time those features have mostly all become "official". For instance, the only reason I'd justified keeping the "Join" cookbook around was because the multi-line Zed scripts would have been miserable to work with in the old editor, but now we have a multi-line editor so that's moot, hence I dropped it here since users can now effectively follow the Join tutorial from the Zed docs right in the Zui editor. For the last remaining content that I'd have put under that "cookbook" umbrella I've instead created this category of "Advanced Guides", which was a term I borrowed from another docs site. My somewhat arbitrary take on when the line gets crossed to "Advanced" is when users drop to the shell to combine outside-the-app CLI functions with clicky functions in the app.
I dropped the "Migration-for-Version-0.29.md" article since I figured enough time had passed for active users to make the transition.
I'd been capitalizing names of articles in hyperlinks in the past (e.g., "Troubleshooting") but we don't seem to do that in the new Zed docs and I realized I like that look more, so I've mimicked it here.
Because we'll want the existing Brim wiki to remain in place until we release Zui v1.0.0, and some other changes will happen to the website/repos at that time, I'm aware of several things that'll have to happen relative to pushing that release.
To-do before merging this PR:
notify-docs-update.yaml
tomain
To-do ASAP after we release Zui v1.0.0:
docs-publish.yml
Actions automation that's been publishingdocs/
to the GitHub wikiFixes #2480