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

Brim wiki updates for v0.25.0 release #1723

Merged
merged 29 commits into from
Jun 25, 2021
Merged

Brim wiki updates for v0.25.0 release #1723

merged 29 commits into from
Jun 25, 2021

Conversation

philrz
Copy link
Contributor

@philrz philrz commented Jun 24, 2021

Apologies in advance for the size of this PR. Due to the need to hyperlink between articles, this would have been difficult to do in small pieces. To do my own proofreading, I've cloned a copy of the docs in this branch to a separate repo that similarly publishes to a GitHub wiki. Therefore my suggestion to reviewers might be to just read that over at https:/philrz/scratchwiki/wiki with fresh eyes rather than try to make sense of every diff.

The approach I'm taking with this PR is to show up-to-date info about the new Brim without completely replacing all of the old content. This is due to the fact that Windows and Linux users will not be auto-updated the new release, and in the event users report big bugs right after we release v0.25.0, we might not even push users to upgrade super fast. So there may be a period when users will want to self-service with docs about their older release and/or I might need to send such links to help users. It would have been nice if we could maintain a single article on each topic and have the parts specific to old/new versions at the relevant spots, but due to the largeness of some changes (the Brimcap unbundling, the role of the Zed Lake, etc.) this became unwieldy for some articles. For those couple bigger topics, I ended up keeping the older content under its existing filename in hopes of not breaking too many bookmarks/hyperlinks in the interim, but added a blurb up top noting the relevant version and linking to the parallel doc that covers the newer. Meanwhile each one covering the newer Brim is at a new filename for now. After we've had a couple follow-on releases beyond v0.25.0 and it seems like most/all users have transitioned, I can move the newer content to the original filenames and phase out the old content entirely.

Since this was an opportunity to reassess and re-test a bunch of the docs, I changed a few other things along the way.

  1. I noticed I've had to keep adding tables to articles showing paths on the filesystem where the app binaries and/or user data are stored, and that was about to get worse because the app binaries have different paths with the new installer. Therefore I've created a separate article just about the filesystem paths, which also provided a nice opportunity to explain the read-only/read-write nature of each. I think it also made the other articles a little cleaner.

  2. The Geolocation article started to look out of place after the other stuff had been overhauled, so I ended up moving it to the Brimcap wiki. See Geolocation article (moved from Brim wiki) brimcap#104 for details.

  3. With 20/20 hindsight, I can see how the Join article I wrote for v0.24.0 is not great (too much leading text, too Zeek-specific, etc.) so I didn't want to invest time in trying to make an updated version of that content. Instead I've added the placeholder blurb at the top of the old article, and once In-line inputs for automated checking of docs examples zed#2627 gets merged I intend to write proper join coverage where it belongs in the Zed operators doc. After that, I think I will create a parallel Join article that shows the v0.25.0 approach of using zapi outside the app and pushing joined data back in, and it'll link to that operator doc.

Closes #1694

@philrz philrz requested review from nwt and a team June 24, 2021 19:19
@philrz philrz self-assigned this Jun 24, 2021
@philrz philrz merged commit cb3443a into main Jun 25, 2021
@philrz philrz deleted the dual-wiki-articles branch June 25, 2021 15:43
@philrz philrz mentioned this pull request Oct 13, 2021
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.

Brim wiki articles with v0.24.0/v0.25.0 guidance
2 participants