Documentation should link to the zlstools docs site if that is the primary docs location?

[nurpax]

I only now found out about the zigtools.org documentation site for ZLS and other Zig tools. This looks good, although it's not immediately clear if this is "first party content" or some other random site.

However, nothing on the VSCode plugin page (screenshot below) links to this docs site:

Assuming zigtools.org is the right place to look for ZLS setup instructions, it'd be really useful to link back to it from the VSCode plugin extension docs.

[Techatrix]

The extension's README links to the ZLS GitHub page which link to zigtools.org in the Installation section. So it is reachable although not directly. I added a link to https://zigtools.org/zls/install/ in the About section of the ZLS GitHub page. That should help a bit since its visible without scrolling down.

Here is what I think we could do:

• update the extension's README. Move ZLS into its own heading an link to zigtools.org directly. This can also be used to clarify the relationship between vscode-zig and ZLS
• show a message in the editor when the user installs ZLS for the first time. The message can offer two buttons "open ZLS GitHub" "open Documentation" or similar that would link to the github and website respectively.

[nurpax]

I think the README (which I imagine is the one that shows up on the VSCode extension marketplace?) change would be good. Now it looks more like a placeholder that doesn't invite me to actually read what's written on it. Perhaps make it less about what features this has and more about how to set it up (clearly link to zigtools if that's the best for docs).

Of course an alternative would be to make the README include all this but that's probably a bit too much of updating. Quite frankly, having written some VSCode extensions (and certainly used a bunch), it's not always quite clear what's the right place to go read the docs.

[nurpax]

The VSCode settings page could perhaps be a bit more verbose of what is expected of the user to set things up for a successful "Build on Save".

The extension settings now has two knobs for "Build on Save". It's not clear what's the difference? I think I set both of these but there was no visible change in VSCode. Not even any kind of a spinner in VSCode indicating that something's being built when I hit ctrl-s. Similarly, the requirements from build.zig on how to setup "zig build check" to work. In an ideal world, this would also be mentioned in the settings since nothing just happens if the build.zig doesn't offer a check target.

[Techatrix]

Perhaps make it less about what features this has and more about how to set it up (clearly link to zigtools if that's the best for docs). [...]

One of the reason why the README is lacking any "How to Setup" instructions is because the extension is intended to work out of the box without additional user input. The extension takes care of installing Zig and ZLS. It is not a strict requirement to look for extra documentation about this extension. Question is how we document additional/optional features like build on save.

The VSCode settings page could perhaps be a bit more verbose of what is expected of the user to set things up for a successful "Build on Save". [...]

I agree, here are some small steps we can take that can improve the situation (in addition to what I mentioned before):

• update https://zigtools.org/zls/editors/vscode/ to mention the build on save setting and link to https://zigtools.org/zls/guides/build-on-save/ (this already the case for the other editors)
• link to https://zigtools.org/zls/guides/build-on-save/ in the setting description for zig.zls.enableBuildOnSave
• update the description of zig.buildOnSave to warn against usage with zig.zls.enableBuildOnSave
• show a warning to the user if they enable zig.buildOnSave and zig.zls.enableBuildOnSave

Perhaps it could also make sense to remove the zig.buildOnSave feature entirely. This would need more discussion though

While build on save can undoubtedly be a useful feature to many Zig users. I wouldn't go as far as to have the documentation expect them to enable it as part of their initial setup process.