search

brimdata / zed

A novel data lake based on super-structured data
https://zed.brimdata.io/
BSD 3-Clause "New" or "Revised" License
1.38k stars 67 forks source link

Add a couple section headers in language overview doc #5175

Closed philrz closed 2 months ago

philrz commented 2 months ago

I added mention of the Zed language // comment syntax back in #4308 after a community user reported not realizing this concept existed (#4302). Another community user just pointed out via https://github.com/brimdata/zed/issues/4310#issuecomment-2214786576 that the way it's covered in the docs now doesn't currently bubble up nicely in the search results. I'm not 100% certain if their proposed change of adding a section header would improve that, but rather than investing time into setting up a test sandbox to investigate, I spent some time re-reading the page to see if adding a header makes sense regardless.

Looking at it through that lens, indeed, I can see that the coverage as it's been feels a little "tacked on", but I was always had trouble coming up with a better idea. Having a wholly separate page under "Language" at the same level as "Expressions", "Operators" etc. just to briefly mention comments feels like overkill. I also don't see a different existing page into which it would graft nicely as a header-worthy section, though I'm open to suggestion.

The "Overview" page should surely be brief, so I respect the urge to avoid lots of section headers there. However, I did ultimately find that adding a "Search and Analytics" header feels pretty natural to me, so once I've got that, the header for Comments feels a bit more natural, too.

As for the user's point in #4302 about if we should divulge the gotcha here about multi-line /* */ comment syntax being available in ZSON but not Zed language, I'm holding off on that for the moment in hopes it might be easier to just enhance the parser. 🤞

philrz commented 2 months ago

Now that this has been merged and the Zed docs site has been re-indexed by our search tool, I'm pleased to say that a search for "comment" is indeed now showing the top hit being the section in the Language Overview page. 🎉 Thanks for the idea @chrismo!

image

(Alas, at this moment that's only true if the "Next" docs revision is selected in the drop-down, since these changes weren't in the docs tagged for the most recent GA release. But I do hope to have a new release out quite soon, so this'll continue to improve.)

chrismo commented 2 months ago

Looks great!