search

vlang / v-analyzer

The @vlang language server, for all your editing needs like go-to-definition, code completion, type hints, and more.
MIT License
86 stars 9 forks source link

docs: provide quickly accessible instructions #101

Closed ttytm closed 2 months ago

ttytm commented 2 months ago

Currently, it is easy to lose overview or to miss information in the instructions of the readme since providing instructions for different platforms and editors can easily become mixed up.

E.g., we have instructions for installation followed by building, then a setup section that mixes some general settings with VS Code related settings then coming to editor specific setups.

To solves this I set up some wiki pages. With the updates to the readme an overview is provided that allows users to access instructions more targeted and directly (and in potentially in more detail). This should help users more easily get v-analyzer up and running.

Rendered preview on the fork: https://github.com/ttytm/v-analyzer/tree/docs/wiki?tab=readme-ov-file#usage

spytheman commented 2 months ago

The Wiki is a github feature, and is not part of the cloned repo.

Imho the README should have enough actual instructions in it, for building the project, not just links to a wiki.

ttytm commented 2 months ago

I think it depends on the project if it makes sense. Since an lsp is cross-platfrom and cross-editor it imho helps to keep an overview and get qicker to what is searched for. To share example of LS projects that I use daily:

To extend the list those are some first finds doing a qiuck search:

ttytm commented 2 months ago

As an alternative I'd add another MD file to better structure the instructions and add a TOC / some links to the headings in the readme and markdown file. Tho my preferred solution would be to utilize the wiki

spytheman commented 2 months ago

Rust analyzer has: image The link is to their website, not to a wiki (that is not vettet and reviewed, and that can change at any moment).

Gopls has: image

The links are mainly to .md files in its repo, so commits to them can be reviewed and vetted, and the files are also present on checkout, so once someone clones the repo, he/she has everything needed to work on it, including the instructions, without having to visit a wiki.

Lua's language server has: image

The links there vary, some are to their wiki, some are to their website (which is presumably under version control and vetted).

ccls readme has: image The link is to https://github.com/MaskRay/ccls/wiki, and the instructions there are circuitous :-| image

Imho ccls is not a good example to follow at all in this aspect.

Haskell's one: image The links are to its documentation website, and they are at least direct there: image

Imho, at least a small section with instructions for building it with v build.vsh debug should stay. The rest can be moved to either a wiki, or to .md files. I am not sure what is better for the user experience, but I am more inclined towards .md files in the same repo, perhaps in the existing folder docs/ ?

ttytm commented 2 months ago

K I gonna look into something md based.

The docs folder that only held assests is no more since 882fb1533f8de07c247cf2189bc439da818dd231 😬

Maybe a INSTALL.md in the root, we can also add a CONTRIBUTING.md if we have enough instructions for it.