Skip to content
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

Merged
merged 11 commits into from
Mar 3, 2023
Merged

Update docs for Zui name change & Docusaurus #2531

merged 11 commits into from
Mar 3, 2023

Conversation

philrz
Copy link
Contributor

@philrz philrz commented Sep 13, 2022

These changes give the wiki a much-needed overhaul. This includes:

  • The upcoming app name change from "Brim" to "Zui"
  • The move of the content from a GitHub wiki to a Docusaurus-built site https://zui.brimdata.io/docs on Netlify that can sit alongside the existing https://zed.brimdata.io/docs
  • The update/removal of several articles to reflect continued evolution in the tech

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 to zui.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.

  1. 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.

  2. I dropped the "Migration-for-Version-0.29.md" article since I figured enough time had passed for active users to make the transition.

  3. 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:

  • Change the branch reference in notify-docs-update.yaml to main
  • Make sure the release paths and version numbers in the Remote Zed Lakes article line up with the Zui we actually release
  • Create a new Zui Demo video on YouTube we can link to instead of the ancient Brim Demo one (Feature Tour video: pcap workflows #2705)

To-do ASAP after we release Zui v1.0.0:

  • Fix any hyperlinks in the README/CHANGELOG that were pointing at the old wiki
  • Remove the docs-publish.yml Actions automation that's been publishing docs/ to the GitHub wiki
  • Replace the GitHub wiki content with a hyperlink that points users at https://zui.brimdata.io
  • Re-do the videos in the Installation article once the web site starts mentioning "Zui" on the Downloads page (and mention the new per-machine option on Windows, which should also be reflected in the Filesystem Paths article) (Redo Zui Installation videos & update Filesystem Paths doc #2706)
  • Update the GitHub URLs for issues/etc. from "brim" to "zui" when the repo is renamed (redirects will still work in the meantime)
  • Update the VirusTotal comment to point at a URL in the new Zui docs site instead of the old wiki
  • Update any links in the Zed/Brimcap docs that still point at the old Brimcap wiki

Fixes #2480

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
Copy link
Member

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
Copy link
Member

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.

Copy link
Contributor Author

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.

Copy link
Member

@jameskerr jameskerr left a 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.

@philrz philrz changed the title Update docs for Zui name change & Docusaurus (not for merge until Zui v1.0.0 is released!) Update docs for Zui name change & Docusaurus Mar 3, 2023
@philrz philrz merged commit 1d5cd15 into main Mar 3, 2023
@philrz philrz deleted the zuifi-wiki branch March 3, 2023 22:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Zui-fy the Brim wiki
2 participants