I recently became colleagues with @jfmengels, and I decided to try out his
elm-review tool. I find the repo on GitHub, and I start going through the README. It includes a link to some code in the package, but unfortunately the link is broken, so I take a look at it. I don’t understand the Markdown syntax being used for it, so I end up creating an issue that the link is broken. It then turns out that the link works fine if I browse the README through the package registry, and the syntax is for the Elm documentation tooling to use.
What went wrong? Should I have gone to the package registry to search for
elm-review to begin with? I very rarely use that site for anything other than reading core documentation, and I’m practically embedded in GitHub anyway, so I don’t even think about whether I should use a different page to search for a package. Additionally, I know
elm-review, like many other parts of the Elm toolchain we rely on at work, has a CLI attached which is not published in the Elm registry, so I naturally expect that looking there will give me an incomplete overview.
Maybe the issue is that the package registry and GitHub both rely on the same README file? If there were two different READMEs (e.g. README and PACKAGE_README), then the GitHub one could easily link to the package registry, where everything is displayed as intended.