Documentation for packages removed from Core is too hard to find

[Alexander Biggs]

If I google "elm keyboard" today, here is the series of steps I follow before figuring out how to do keyboard input in my Elm game:

1. Click on first result, "Keyboard - core 2.1.0" packages page

2. Click on "go to latest version"

3. Get redirected to a 404 page

4. Scratch my head for a bit before realizing that the package was moved out of Core in Elm 4

5. Click on "elm-lang" at the top navigation to go to the frontpage for elm documentation

6. I lied, it actually brings me to the elm-lang github organization(?!?). Search for "keyboard" there

7. It brings me to a github repo for Keyboard, whose README has no info on how to install the package or what types are exposed, just a general overview of what the package is

8. Go back to the elm package website, click on the "Elm Packages" icon on the topleft to go to the documentation homepage

9. Search for "keyboard", click on first result.

The page this shows me still has no documentation on how to install the package, for that I have to click back and go to "Using Packages" from the package homepage. However, finally I can find the documentation for what types are available in the Keyboard package by clicking on "Keyboard" on the right side of the page.

This process can be improved a lot:

1. The "go to latest version" for packages removed from core should redirect to the new page for that package

2. Pages for packages that are not in Core should have a link to the installation instructions

3. The "elm-lang" link at the top of the packages navigation should go to the documentation frontpage, to avoid breaking the idea of a navigation tree.

Any thoughts on other ways we can improve the process for getting started with elm packages?

[Noah Hall]

https://github.com/elm-lang/elm-platform/blob/master/upgrade-docs/0.17.md#update-elm-packagejson

> --
> You received this message because you are subscribed to the Google Groups
> "Elm Discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to elm-discuss...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Noah Hall]

(not saying it can't be improved - but this is where the info for
core/evan's packages live)

[Joey Eremondi]

Perhaps there could be an option for a "landing page" or multi-version README, so the documentation for the old versions can point to the new versions? Like, a PackageInfo.md in master on GitHub?

Or maybe, when a library is deprecated, it should be good practice to release a "dummy" version with all contents removed, an unsatisfiable version constraint, and a README pointing to the new library?

In any case, we can't control how Google presents our documentation, so there will probably need to be some kind of workaround.

[Alexander Biggs]

Makes sense, but remember that most users who are new to Elm will not be checking the upgrade doc from a version they never used.