Reorder installation instructions

[straight-shoota]

I'd like to pick up on my suggestion in #86 (comment) to improve the order of platforms listed on the Install page.
Currently, it seems to not follow any particular order. At least it's not visible.
While it's not super important, I think it can help people to proceed with installation.
Alternatively, we could just order lexically.

Relevant factors for sort order are:

1. Popularity of the platform
   We don't have any statics for platform popularity, but I suppose the majority of Crystal users is probably something like macOS, Ubuntu, Arch/Manjaro, Alpine, WSL

2. Availability of official Crystal distribution package
   Native packages are provided for macOS and Linux distributions using APT or RPM. Binaries are available for macOS and generic Linux.

3. Availability of Crystal package in platform's native package system
   Alpine, Arch, FreeBSD, Gentoo, Void maintain Crystal packages.

from sources and from .tar.gz are special because they are not instructions for specific platforms but generic distribution methods. Theoretically, they could be treated like snapcraft and linux brew and included in (almost) every platform's installation instructions. But they are usually more effort than installing a package, so that's usually preferred. It might make sense to at least mention the generic binary releases on linux distributions (maybe only on those that don't provide a package).

These platforms, that don't provide a genuine installation method but only through snapcraft the availability of Crystal is a bit thin. Snapcraft is not a native installation, it's a governed sandboxed environment. If I were a user of one of those distributions and see installation instructions that require me to use snapcraft, I'm pretty sure I'd simply jump ship because I want to use Crystal, not Snapcraft.

This affects Elementary OS, KDE neo, Linux Mint (shouldn't that be able to use the APT package?) and Manjaro (AFAIK there is a Crystal package). IMO it would be best to remove those platforms that only provide installation instructions using snapcraft.
Technically, almost all Linux distros should be able to install Crystal using linuxbrew. I don't think we want to list literally all distros and provide installation instructions using linuxbrew either.

Alternatively, we could consider adding Linuxbrew and Snapcraft as generic distribution methods in the same category as from sources and .tar.gz. So if you're using one of these tools, you can immediately get installation instructions for that platform as they're not distro-specific.
We could still leave references to Linuxbrew and Snapcraft in the respective distros' instructions.

[bcardiff]

Regarding snapcraft:

• There have been 360 active weekly users for the last couple of months.
• The Crystal snap package is not actually sandboxed since uses classic confinement.

Regarding grouping of information:

I believe the installation menu should allow the user to recognize if possible the environment been used and from there know the option. Otherwise the user needs to check general methods like snapcraft or linuxbrew + their distro to learn about the package.

This is for new comers. Usually a one time experience for each of us. The information need to be as direct as possible.

[straight-shoota]

I believe the installation menu should allow the user to recognize if possible the environment been used and from there know the option.

That's the best approach, but it can also be overwhelming because there are numerous linux distributions and

• all of them support .tar.gz install
• all of them should work with Linuxbrew
• many support Snapcraft (and that number may increase in the future)

Should we list each of them?

This is for new comers. Usually a one time experience for each of us. The information need to be as direct as possible.

I agree. But having to filter out your platform from a number of icons that only provide generic instructions for snapcraft is not very direct either.

Maybe we could employ platform detection in the browser to highlight the current target platform.

[bcardiff]

all of them support .tar.gz install

I consider .tar.gz special so I would not include that.

all of them should work with Linuxbrew

I am not sure it works in all distros. At least not from the official page. So I would not advertise linuxbrew in all distros.

[straight-shoota]

I'm no expert either. So let's say there are many distros that support Linuxbrew. And I'm sure we can agree that there are more than we're currently listing. There are even a lot of APT- and RPM-based distros that should just work with our packages as well but are not (yet) listed here.

IMO it doesn't make sense to start listing each and every linux distribution that supports any of Crystal's distribution method.

Maybe a better approach would actually be to provide instructions for specific distribution methods.
That's how Ruby's installation page is structured and I like it. It's clearly arranged and you can easily navigate to your preferred installation method. There is no need to list numerous linux distributions when there are actually just a hand full of different (main) package systems.

[bcardiff]

My take is that if the problem is the long distro menu list, then platform detection with optionally listing everything can help.

If we want a raw list of all possibilities grouped as in ruby it can work as a more advance way, but I found it hard to beat the [pick your distro] -> [here are the options] experience for new-comers.

[straight-shoota]

Discoverability is one problem and that yeah can be mitigated by platform detection. But I doubt that distinguishing individual linux distributions can work that well in a browser.

The main problem is that we can't possibly maintain a complete list of all Linux distributions that support some method of installing Crystal. There are just far too many. And many are less prominent, but still support some kind of standard installation method.

When there is no way to complete such a list, I think we shouldn't even try to start. Because if we do, there will always be missing distros. And users from that distro won't find their installation instructions. Maybe they would turn to a related distro and try if that approach works. But that already requires context information: You can't look for your package manager, you need to know another distribution that uses the same one.

[bcardiff]

1. Let's create a small list to cover installation from different means (from apt, from tar.gz, from source, from linuxbrew, etc...) grouped similar as in ruby.
2. Put that list after the distro icons
3. Put the content probable in partials so they can be reused and avoid 100% duplication

Let's check in a couple of months from site stats and if there are distros not used we can shorten the distro list.

So we keep general installation methods for flexibility but the distro menu for friendlier first time.

[j8r]

I have also a suggestion, that is common out there.

1. Show supported platforms with text/icons.

• Source
• Linux
• macOS
• Windows
• FreeBSD

2. After clicking on one of this, list the available means to get Crystal, depending of the platform:

• tar.gz.
• brew
• Docker
• snap
• package manager (apt/rpm/aur)
• etc
  Go do this – though it only list one option, and Elixir.

An advantage is there are less information, we know directly the supported OSes.

I would like to add: no need to specify specific distributions. If an user is using a package manager through the CLI, (s)he is advanced enough to know if its distribution is apt/rpm based and on which family it is based on (Debian, Ubuntu, RHEL...). That what it is also assumed by Elixir.

[straight-shoota]

I support having a hierarchy based on the operating system and installation type. Whether that should be on separate pages, is a different story. IMO it would probably be better to have a two-layered hiearchy on the index page. That's still a concise arrangement. And the instructions for each installation method would be on a separate page like it is now.

Also, we could still consider a distribution-based lookup. That doesn't have to be mutually exclusive. But it should be on top of that, and only added when we see it's necessary. However, on the basis that most other software installation instructions don't do this, I'm pretty certain we don't really need that either.

[straight-shoota]

As basis for further consideration, I compiled a list of all the installation methods I'm currently aware of.
I added some classification of ownership, both for the package management system in general and the Crystal package. I think this could be worth mentioning. For example, while we maintain the upstream project and provide installation instructions, we're not responsible for community-maintained packages.

- name:  APT 
  package_manager: system
  package_maintainer: crystal
  platforms:
  - Debian derivatives

- name: RPM 
  package_manager: system
  package_maintainer: crystal
  platforms:
  - Red Hat derivatives

- name: Arch repositories 
  package_manager: system
  package_maintainer: system
  platforms:
  - Arch Linux

- name: Aports 
  package_manager: system
  package_maintainer: system
  platforms:
  - Alpine Linux

- name: FreeBSD ports 
  package_manager: system
  package_maintainer: system
  platforms:
  - FreeBSD

- name: FreeBSD package 
  package_manager: system
  package_maintainer: system
  platforms:
  - FreeBSD

- name: OpenBSD ports 
  package_manager: system
  package_maintainer: system
  platforms:
  - OpenBSD

- name: OpenBSD package 
  package_manager: system
  package_maintainer: system
  platforms:
  - OpenBSD

- name: Scoop 
  package_manager: community
  package_maintainer: community
  platforms:
  - Windows

- name: Homebrew 
  package_manager: community
  package_maintainer: community
  platforms:
  - MacOS
  - Linux

- name: Docker 
  package_manager: community
  package_maintainer: crystal
  platforms:

- name: Snapcraft 
  package_manager: community
  package_maintainer: crystal
  platforms:
  - Linux

- name: Asdf 
  package_manager: community
  package_maintainer: community
  platforms:
  - Linux
  - MacOS

- name: Binary archive 
  package_manager: none
  package_maintainer: crystal
  platforms:
  - Linux
  - MacOS
  - Windows

- name: Build from source
  package_manager: none
  package_maintainer: crystal
  platforms:

[straight-shoota]

Resolved by #540 and #416