Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://github.com/agda/agda/issues/6866 below:

Make Installation as Easy as Possible · Issue #6866 · agda/agda · GitHub

This is a suggestion to improve the Installation section of the User Manual to make a brand new user's path to having a working Agda as smooth as possible. I'd be happy to turn this into a PR but would like feedback first on the approach.

A note on the importance of this: Not everyone comes to Agda determined to love it and learn it. I would guess that most come out of curiosity, looking for something fun and interesting, and they may be time-poor. If their first experience is frustrating then there may not be a second experience, so everything else great about the language no longer matters.

In my opinion a much better installation guide is The Getting Started chapter of Programming Language Foundations in Agda (PLFA). I don't see why the happy path of the Agda Installation instructions shouldn't be this simple, with more obscure instructions relegated to footnotes or an easily skipped section.

There are two broad ways to structure this sort of page:

1. One-size-fits-all, with platform-specific notes, or
2. Platform-specific instructions.

But this page has evolved to be both one-size-fits-all and platform-specific! Add a third dimension of the type of install, with a sub-dimension of cabal-or-stack, plus some instructions for enable-cluster-counting, some instructions for Emacs configuration and it all gets very confusing for the beginner.

The current Installation section of the User Manual has these issues, as I see it:

1. The page starts by telling the user that there are several ways to install Agda, but it doesn't recommend one for users just getting started.
2. Step 1: Prerequisites lists GHC, cabal-install, Alex, Happy and GNU Emacs. I think it should just be GHC and Cabal, and it shouldn't mention these except to tell users how to install them using ghcup (a footnote could mention stack as an alternative to ghcup).
3. The Installation from Source section is cluttered with instructions on e.g. ICU and Cluster Counting, explanations of ieee754, etc.
4. The Windows binary version appears to be unmaintained (it is for Agda 2.6.0.1) and not officially supported,
5. The debian/ubuntu instructions tell users to install the agda-mode package, which doesn't exist.

Enough complaining. Here's what I think should change:

1. Start with a preamble which explains that the goal is to have Agda available on your system, with the Agda Standard Library (agda-stdlib) installed, and a text editor set up for Agda development.
2. Change the top-level of the Installation page to be the installation steps: 'Install Agda', 'Install the Agda Standard Library', 'Install and Configure a Text Editor for Agda'.
3. Change the next level under 'Install Agda' to be the installation scenarios: 'Install as Haskell Package (recommended)', 'Install Development Version from Source', and 'Install as Prebuilt Package (not generally recommended)'.
4. Move 'Installation Flags' and 'Installing multiple versions of Agda' to footnotes under the 'Install as Haskell Package' instructions, and add more explanation of what they mean and how to use the flags, etc.
5. In the 'Install as Haskell Package (recommended)' section (renamed from 'Installation from source'):
   1. Link to ghcup and give instructions for using it to install ghc and cabal,
   2. Give instructions for installing Agda using cabal,
   3. Add a footnote on upgrading Agda using cabal,
   4. Move the stack instructions to a footnote,
   5. Simplify further by moving many of the advanced instructions into the 'Install Development Version from Source' section.
   6. Put some platform-specific advice in here, but only if short, and not as dedicated sections.
6. Expand on the instructions for installing agda-stdlib (in its new dedicated section). The linked instructions aren't very easy to follow. Again, look to PLFA for simpler instructions for beginners.
7. With 'Install and Configure a Text Editor for Agda' now its own section, give some explanation of what the options are (Emacs, vs-code) and why using other text editors may not be much fun. Describe the installation and configuration of Emacs (maybe an aside on forked flavours) and vs-code.

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4