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.
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.
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.
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.
jameskerr
left a comment
There was a problem hiding this comment.
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.ioat 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.yamltomainTo-do ASAP after we release Zui v1.0.0:
docs-publish.ymlActions automation that's been publishingdocs/to the GitHub wikiFixes #2480