Fix website (#294)

Author: anttiharju

docs/README.md

@@ -10,9 +10,9 @@
 
 ## FAQ
 
-**Q:** What about https://go.dev/blog/toolchain?
+**Q:** What about [https://go.dev/blog/toolchain](https://go.dev/blog/toolchain)?
 
-**A:** It is about forward-compatibility, `vmatch` installs the Go version specified in your project.
+**A:** It is about forward-compatibility, `vmatch` installs the Go version specified in your project. I've found Go's promises of backward-compatibility to be squishy in practice, `brew install go` has not been sufficient for some project setups.
 
 **Q:** What about `go run` (Go 1.24 and after `go run` calls are cached)?
 
@@ -42,10 +42,6 @@ Mainly, you should have `~/.vmatch/bin` in your PATH.
 brew update && brew upgrade vmatch
 ```
 
-### Note on expectations
-
-When the specified Go version is downloaded for the first time, it may take a while.
-
 ## Integrations
 
 ### VS Code
@@ -56,7 +52,7 @@ Open your project via `code .` or similar from your shell where `vmatch doctor`
 
 #### golangci-lint
 
-Follow guidance at https://golangci-lint.run/welcome/integrations/#visual-studio-code but specify the full path of your ~/.vmatch/bin/golangci-lint as an alternate lint tool, like this:
+Follow guidance at [https://golangci-lint.run/welcome/integrations/#visual-studio-code](https://golangci-lint.run/welcome/integrations/#visual-studio-code) but specify the full path of your ~/.vmatch/bin/golangci-lint as an alternate lint tool, like this:
 
 ```json
   "go.alternateTools": {
@@ -66,7 +62,7 @@ Follow guidance at https://golangci-lint.run/welcome/integrations/#visual-studio
 
 ### Renovate
 
-I _think_ one can configure Renovate to maintain the `.golangci-version` file for you, see https://www.jvt.me/posts/2022/12/15/renovate-golangci-lint/ for an example.
+I _think_ one can configure Renovate to maintain the `.golangci-version` file for you, see [https://www.jvt.me/posts/2022/12/15/renovate-golangci-lint/](https://www.jvt.me/posts/2022/12/15/renovate-golangci-lint/) for an example.
 
 ## How
 
@@ -95,27 +91,14 @@ Go versions are downloaded from Google servers and stored under `~/.vmatch`, lik
 
 Contents of `~/.vmatch/bin` are symlinked from `$(go env GOPATH)/bin`, expect for `go` or `golangci-lint`, because those are shell scripts that wrap `vmatch`.
 
-If your `go.mod` does not specify the full version, for example `1.24` instead of `1.24.3`, `vmatch` defaults to `1.24.0` for simplicity, surprisingly, sometimes there is a Go 1.minor and sometimes a Go 1.minor.0 version released. https://dl.google.com/go/go1.20.darwin-amd64.pkg and https://dl.google.com/go/go1.21.0.darwin-amd64.pkg are examples.
-
-## Stargazers over time
-
-[![Stargazers over time](https://starchart.cc/anttiharju/vmatch.svg?variant=adaptive)](https://starchart.cc/anttiharju/vmatch)
+If your `go.mod` does not specify the full version, for example `1.24` instead of `1.24.3`, `vmatch` defaults to `1.24.0` for simplicity, surprisingly, sometimes there is a Go 1.minor and sometimes a Go 1.minor.0 version released. [https://dl.google.com/go/go1.20.darwin-amd64.pkg](https://dl.google.com/go/go1.20.darwin-amd64.pkg) and [https://dl.google.com/go/go1.21.0.darwin-amd64.pkg](https://dl.google.com/go/go1.21.0.darwin-amd64.pkg) are examples.
 
-## Retrospective on the project
+## Usage
 
-While developing `vmatch`, I learned a lot about Go, `brew`, GitHub Actions, Git pre-commit hooks, and developer tooling. There's a surprising amount of detail that has to be accommodated in many places.
+After you have completed the installation, you can simply use `go` and `golangci-lint` as usual, as long as there's a `.golangci-version` or `go.mod` file available in current directory or above.
 
-I think this project could be pushed a lot further, especially in terms of where it is distributed, and adding new features like always being on the latest patch of `Go`. Unfortunately life is too short, and the project is at a state where it is very usable for my personal use.
+Note that when a version is downloaded for the first time, your commands may appear to hang. The time it takes depends on your internet speed and computer.
 
-Long-term, `Nix` (see https://nixos.org), would likely be the generic solution for managing your development environment. Rolling it out to an entire team might have a relatively high barrier, even with projects like `Flox` (see https://flox.dev), so `vmatch` attempts to be a low-barrier-of-entry solution.
-
-If you find bugs, issue reports are very much appreciated and PRs are welcome. If you plan to push the project a lot further (for example managing `node` in a similar fashion), I'd recommend you to maintain a fork, say, `vmatch-node`.
-
-During the project a lot of supporting infrastructure was set up:
-
-- https://github.com/anttiharju/homebrew-tap/tree/fe24baf82fb570b6ec74694750080789742750e7 (whopping 174 commits, corresponding roughly to the same number of releases!)
-- https://github.com/anttiharju/actions/tree/v1 (whopping 20 composite actions!)
-- https://github.com/anttiharju/check-relative-markdown-links/tree/f79dc07684109baed16d10dd8ff2ade9bb94ce22 (a bash prototype for a tool that's more generally applicable and therefore useful than `vmatch`)
-- https://github.com/anttiharju/editorconfig/tree/9fa1679fcb6d55ed841a2ad36d142afd2d7cf30f (a centrally managed editorconfig distributed via GitHub Actions to my repositories!)
+## Stargazers over time
 
-all of which make it easier for me to build new tools, on-demand, with minimal effort spent on trivial things like tooling automation. With [Go rewrite of `check-relative-markdown-links`](https://github.com/anttiharju/check-relative-markdown-links/issues/5) being the first!
+[![Stargazers over time](https://starchart.cc/anttiharju/vmatch.svg?variant=adaptive)](https://starchart.cc/anttiharju/vmatch)

docs/RETROSPECTIVE.md

@@ -0,0 +1,18 @@
+# Sideproject retrospective
+
+While developing `vmatch`, I learned a lot about Go, `brew`, GitHub Actions, Git pre-commit hooks, and developer tooling. There's a surprising amount of detail that has to be accommodated in many places.
+
+I think this project could be pushed a lot further, especially in terms of where it is distributed, and adding new features like always being on the latest patch of `Go`. Unfortunately life is too short, and the project is at a state where it is very usable for my personal use.
+
+Long-term, `Nix` (see [nixos.org](https://nixos.org)), would likely be the generic solution for managing your development environment. Rolling it out to an entire team might have a relatively high barrier, even with projects like `Flox` (see [flox.dev](https://flox.dev)), so `vmatch` attempts to be a low-barrier-of-entry solution.
+
+If you find bugs, issue reports are very much appreciated and PRs are welcome. If you plan to push the project a lot further (for example managing `node` in a similar fashion), I'd recommend you to maintain a fork, say, `vmatch-node`.
+
+During the project a lot of supporting infrastructure was set up:
+
+- [github.com/anttiharju/homebrew-tap](https://github.com/anttiharju/homebrew-tap/tree/299612d532b3a676f5bfea84c3115ff562c9e23a) (whopping 174 commits, corresponding roughly to the same number of releases!)
+- [github.com/anttiharju/actions@v1](https://github.com/anttiharju/actions/tree/v1) (whopping 20 composite actions!)
+- [github.com/anttiharju/check-relative-markdown-links](https://github.com/anttiharju/check-relative-markdown-links/tree/f79dc07684109baed16d10dd8ff2ade9bb94ce22) (a bash prototype for a tool that's more generally applicable and therefore useful than `vmatch`)
+- [github.com/anttiharju/editorconfig](https://github.com/anttiharju/editorconfig/tree/9fa1679fcb6d55ed841a2ad36d142afd2d7cf30f) (a centrally managed editorconfig distributed via GitHub Actions to my repositories!)
+
+all of which make it easier for me to build new tools, on-demand, with minimal effort spent on trivial things like tooling automation. With [Go rewrite of `check-relative-markdown-links`](https://github.com/anttiharju/check-relative-markdown-links/issues/5) being the first!

docs/commands/go.md

@@ -4,4 +4,4 @@
 vmatch go # followed by any args you would give to go
 ```
 
-This command is not meant to be used, but rather, you would have `~/.vmatch/bin/go` in your path as the `go` program.
+This command is not meant to be used directly, but rather through `~/.vmatch/bin/go` which should be the `go` in your PATH. Whether this is the case can be verified with [`vmatch doctor`](./doctor.md)

docs/commands/golangci-lint.md

@@ -4,4 +4,4 @@
 vmatch golangci-lint # followed by any args you would give to golangci-lint
 ```
 
-This command is not meant to be used, but rather, you would have `~/.vmatch/bin/golangci-lint` in your path as the `golangci-lint` program.
+This command is not meant to be used directly, but rather through `~/.vmatch/bin/golangci-lint` which should be the `golangci-lint` in your PATH. Whether this is the case can be verified with [`vmatch doctor`](./doctor.md)

docs/commands/version.md

@@ -1,4 +1,4 @@
-# golangci-lint
+# version
 
 ```sh
 vmatch version