RFC: Improve and restructure Cabal user guide

[m-renaud]

Hey all, I wanted to start a discussion about ways the current user guide can be improved. I felt like now may be a good time since the release of cabal-install 3.0 is imminent, and comes with a bunch of usability improvements from the v2-* commands.

Summary of Observed Issues

• Lack of a to-the-point "Quick Start" at the beginning of the user guide
• Dual meaning of "Cabal"
• Lack of focus on "private/project-based workflows"
• Redundant/outdated information across old-style/new-style docs

Quick Start

Currently, if I'm simply looking for a 1-2 sentence summary of what cabal (read: cabal-install) is and how to get started with it, I can't find one. This is especially troublesome for folks new to Haskell and its build tools who have very little if any pre-requisite knowledge.

To start, a web search for "haskell cabal quick start" gives you:

1. A link to section 3.1 (Developing Packages) which is definitely not a "quick start" since it already "assume(s) we have created a project directory and already have a Haskell module or two".
2. A link to this repo
3. Blog post
4. Wiki page (unrelated)

None of these are particularly useful. Playing around with search terms you can eventually find the Introduction section which has tonnes of details and gets into the weeds pretty quickly (like that "Cabal packages use the standard compressed tarball format"), with no information for "how to get cabal" or "how to use cabal". You may also find the Nix-style local builds quickstart section which neither sounds "quick start"-ey or is worded as such. It starts with "Suppose that you are in a directory containing a single Cabal package which you wish to build", how am I supposed to get that directory?

In comparison, a search for "haskell stack quick start" prominently features https://docs.haskellstack.org/en/stable/README/ which has all the info you need: a short summary of what it is, how to get it, and how to use it which all fits within a couple screens and doesn't have superfluous information. Similar docs can be found for build tools of other languages as well (Rust, Go, Elm, etc.)

Dual meaning of "Cabal"

I'm sure its been mentioned before, but the fact that "Cabal" can refer to either "a package system for Haskell software" or "a tool for working with packages" can definitely cause confusion, especially those new to the ecosystem. I obviously am not proposing changing the name of either of these, just pointing out that there's ambiguity which makes it very important how content is introduced.

In the docs, the "Cabal the package system" receives more prominence early on than "cabal the build tool" which I think is backwards, since when people first enter the Haskell ecosystem they will begin by encountering "cabal the build tool". They should both be introduced early on of course, just the other way around.

Lack of focus on project-based workflows

All the existing docs assume the use case being addressed by cabal is to develop Haskell packages (read: OSS packages to be uploaded to Hackage). Within this there are two sub-use cases: 1) Starting a new Hackage package from scratch, and 2) Forking an existing Haskell package and hacking on it, the latter being more common.

There is a third use case: what I'll call "project-based workflows", or in other words, new Haskell "projects" which are not meant for public distribution. This group includes many things: simple playground for trying something out, following along with a tutorial, class work for students, private projects, etc. I wager this is the most common use case for cabal-install since only a very small fraction of "packages" that are started become packages on Hackage, and the set of contributors to existing Hackage packages is limited; these two groups are dwarfed by those of beginners, students, and hobbyists.

Reading through the current user guide you learn about installing local packages you've already written, and configuration (like executable-stripping and repository specification) before you learn how to create an empty package, build, and run it. This seems wrong to me.

Redundant/outdated information across old-style/new-style docs

The wording and examples throughout are often referring to old-style use of cabal, whether it be old-style build, sandboxes, locally installing packages for use in a project, etc. Most of the sections in the user guide could use pretty big restructurings (Section 2.2.4 - Developing with sandboxes in particular).

Proposed Changes

Introduce a "Quick Start" section before the current "Introduction"

This would provide a very short and concise overview of "cabal the build tool", how to get it, and how to use it to create a simple Haskell project. It would mention that "cabal" refers to both a "build tool" and a "packaging system", but anyone looking for a "cabal quick start" is almost certainly interested in "cabal the build tool". This would mostly address the first 3 issues I mentioned above, although (3) will require some changes throughout.

Don't focus entirely on the "Hackage package" case

This would probably involve mild wording changes throughout, exact words TBD. Having the "Quick Start" section goes a long way as mentioned above.

Make v2-* commands the default throughout

• Use v2-build/v2-run in "Quick Start" and in "Introduction" call out old vs. new way
  • Put the FUD about old cabal to bed early on, with concrete example in the "Quick Start" for the modern way of starting a Haskell project with cabal, no cabal hell or sandbox nonesense ;)
• Move "sandbox" sections to the end (in a legacy section), maybe with a note here and there about how things used to be done
• Move "Nix-style local builds" content to the section about configuring and building packages

Who's going to make all these changes?

I will! But before I do, I want to get consensus on the general shape of the changes because having these discussions on individual PRs is a pain.

All thoughts and comments welcome!

[23Skidoo]

For my previous ideas on improving documentation, see https://github.com/haskell/cabal/wiki/Hackathon-2017#not-critically-important-but-good-to-have.

[23Skidoo]

Re: Cabal the library/cabal the tool confusion, see #3965 (comment) for the future direction.

[23Skidoo]

@m-renaud Overall, I think that your suggestions make a lot of sense and will be a huge improvement. Cabal's documentation definitely needs some TLC, so thanks a lot for volunteering to work on this!

[hvr]

I'd suggest to do this incrementally in smaller logical/focused steps (I'm worried that having a too large PRs will get dragged down by being too tedious to review + being subject to bikeshed if too much surface is offered); and let's start with the most urgent (and hopefully non-controversial) parts first; such as addressing the concern raised in #6213

[m-renaud]

Reviving this thread :)

@hvr completely agreed. I'd like to start by creating a "Section 0. Getting started with Haskell and Cabal" (similar to Rust - Getting started) which is focused at newcomers to the language to reduce the barrier of entry to Haskell. This will also put to bed the FUD about old cabal hell by clearly laying out the workflow for going from zero to working Haskell application.

I'd then continue on #6157 to modernize the "Developing packages" docs using the most recent best practices and update to v2- commands.

Next would be to fold the "Nix-style local builds" content into the previous sections where it makes sense. Concretely this means removing the "sandboxes" section and other old cabal hell workarounds and commentary. This is a larger body of work and there's various ways that it could be structured.

All that I ask is that we don't let perfect be the enemy of the good here. I'm more that willing to help improve the docs situation here, but I'm just concerned it will be very hard to get any changes merged in if not everyone is 100% happy with any particular PR. If I can could get some support for the broad direction with the understanding that these will all be incremental improvements and any particular PR should not be taken as the end state, that would help a lot in keeping up the momentum.

Let me know what you think!

[phadej]

Rust - Getting started

• it is very terse, too terse. We should be able to assume that person can spend more than one minute on a similar page. We still need to have good structure to allow "quick scanning".
• Lacks forward pointers e.g. cargo build isn't a link to tutorial nor the command reference - it should. We can improve there.
• AFAIK Rust has some support for having multiple crates (like cabal.project), but that page doesn't help on that. Not that it shouldn't, but as said elsewhere I'd try hard to workaround not using word standalone project. It is not defined, and means completely different things for people with different backgrounds.

Developing packages

Should be split into tutorial part and the reference part. They should be separate pages.
I have no opinions on what goes into tutorial part. Reference part should be complete.

Removing sandbox references

👍 ... if someone needs to know about sandboxes, let them look into old docs.

Folding nix-style local builds

I'm not sure. If it means folding tutorial parts into other tutorial-like pages, that is ok.
References have to stay as references. Again, separation would be great.

---

I think that starting with separating tutorial and reference parts would be just moving text around,
and could be done right now. And I strongly suggest doing that soon. I'm occasionally improving the reference parts as I go through the code (and find out that something "obvious" is not documented).

[m-renaud]

Rust - Getting started

Agreed with all your points, I can put together an initial PR and then we can collaborate on structure and wording there.

Should be split into tutorial part and the reference part

👍 I guess part of the "tutorial" would be the "Section 0. Getting started with Haskell" (newcomer focused), and then we can split the current developing-packages.rst into a "This is how you create a package and upload to hackage" tutorial, and then reference section which explains how everything fits together.

Folding nix-style local builds

Yeah, I care less strongly about this. Would be good for general doc health but unclear exactly which users benefit from it.

[Mikolaj]

@JonathanLorimer, @emilypi: look what I've found!