Improve the provision of installation instructions

[wilfwilson]

Sorry this is a bit vague, but this is based on the experience of a least one real-world GAP user who has passed on their experiences to me.

I thought it was a good idea to record these concerns here, in case someone (perhaps me) touches these parts of the website in the coming months, and has ideas about how to improve things.

Installation pages

The GAP website contains installation instructions at https://www.gap-system.org/Download/install.html and https://www.gap-system.org/Download/tools.html, with tangential mentions on the individual downloads page https://www.gap-system.org/Releases/4.11.1.html. There are also extensive (and very good) installation instructions on the main GAP GitHub development repository at https://github.com/gap-system/gap/blob/master/README.md and https://github.com/gap-system/gap/blob/master/INSTALL.md.

The specific issue that my correspondent had was that GAP was not installing because (as it turned out) they did not have a C or C++ compiler installed on their computer. Although having a compiler is mentioned on some of those pages, on the specific page https://www.gap-system.org/Download/install.html (from which there are clear no links to more detailed installation instructions) there is no particular mention of this. Their specific request was:

A comment right there, very visible, about prerequisites. This should be a link to a separate page, of course, and there is already more information to be found on the GAP pages.

Perhaps we need to re-think how these several sources of installation instructions relate to each other, and possibly we should unify/de-duplicate some of it. Or perhaps we just need to add more links between all of these pages, or add some information in certain areas.

Windows Subsystem for Linux

On the Downloads pages, we now recommend the Windows Subsystem for Linux for Windows users. We currently have a link to https://docs.microsoft.com/en-us/windows/wsl/about behind the words "Windows Subsystem for Linux".

• Perhaps we should have a sentence explaining what it is.
• We should make sure that we are giving a link to good installation instructions for the WSL (and make it clear that we are doing so). Perhaps the existing link is the appropriate link; perhaps not.
• Similarly, we should have a recommended link to an explanation of the WSL. Perhaps the existing link is appropriate, perhaps not.

[fingolfin]

These are all good and important points. Also CC @ThomasBreuer to whom I just talked about this (he told me about a similar experience by somebody he talked to; perhaps it was even the same person)

[ThomasBreuer]

I had intended to open an issue about the discussion (via e-mail) on last Friday. Now this issue seems to be the right place.
So here is the feedback which I got about the installation instructions:
After downloading the archive, unpacking, and compiling the core system and the packages (all this did not cause problems), the installation page (https://www.gap-system.org/Download/) says that one should "Adjust some links/scripts/icons etc." and "Optional: run a few tests". What is missing is first of all how one is supposed to start GAP --where is the executable? As soon as one knows this, it becomes important how one can leave GAP. It would be natural to have a short page on "Running GAP for the first time", which tells about

• starting GAP,
• entering something at the GAP prompt,
• how to use the semicolon (and what to do if one has forgotten it),
• how to get out of the brk> loop in order to recover from a mistake,
• leaving GAP,
• and perhaps one or two more essential things for a "confident computer-literate mathematician who has ideally never heard of GAP".

The point is that one (well, the user who gave the feedback) does not want to read a tutorial in this situation.