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

Add a couple section headers in language overview doc #5175

Merged
merged 1 commit into from
Jul 11, 2024

Conversation

philrz
Copy link
Contributor

@philrz philrz commented Jul 9, 2024

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 #4310 (comment) 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 philrz requested a review from a team July 9, 2024 22:39
@philrz philrz self-assigned this Jul 9, 2024
@philrz philrz merged commit 1b3744d into main Jul 11, 2024
4 checks passed
@philrz philrz deleted the docs-overview-improve branch July 11, 2024 21:30
@philrz
Copy link
Contributor Author

philrz commented Jul 11, 2024

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

@philrz philrz linked an issue Jul 11, 2024 that may be closed by this pull request
@chrismo
Copy link

chrismo commented Jul 12, 2024

Looks great!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Multiline comments in Zed language
3 participants