I’ve created a new repo for an exciting new prospect that the HF is trying to find volunteers for: a Cabal User Guide. The Cabal maintenance team acknowledges that the current state of docs is… not the best, to put it lightly. More concretely, the Cabal documentation reads more like a reference and a wall of text, rather than an actual guide. We are seeking to remedy this by excising the relevant quickstart/guide content from the documentation, keeping the rest of the documentation as a reference, and creating a new Rustbook-style mdBook effort to satisfy this gap in the documentation. I’ve created the new repo here, and raised its first issue, which is an RFC for content structure. I’d love for you all to be involved. To be clear: HF would love for volunteers to help drive this effort! We want your input, and your contributions.
The below text is redundant with the issue.
This repository intends to create a new Quickstart and User guide for the Cabal build tool. The Cabal team acknowledges that the current state of documents, located at cabal.readthedocs.io, serves more as a reference, and less as a guide for getting started or gathering intuition about how to effectively use the tool on projects. We would like to change this.
Rust has had a very successful, community-driven book built on mdbook, which allows users to contribute markdown to a codebase which may be compiled into a nice, legible and locally hostable book format. I propose we adopt this style, and contribute the missing content for this book in that format.
There are two major areas of content that I’d like to cover:
- Quickstart. How does a user come up to speed in as quickly a manner as possible, such that they can get hacking with minimal fuss. The sample out line for this content would look something like the following:
- Creating a project from scratch
- Working with an existing project, considering existing tooling like
stack, or otherwise.
- Hello world! Building and running a small project to output. This section would probably list a small subset of useful commands.
- User guide. Given a sample project, with a contrived object, how would the user go about:
- Creating the project from scratch. Discussing naming conventions, the anatomy of a simple
.cabaland its components/vocabulary/syntax at a high level
- Modifying a project: adding modules exposed or otherwise, adding dependencies, warnings, etc etc. at a high level, and discussing good practice for naming conventions and managing bounds.
- Building a project: this section could discuss the basic commands used to build a project once a selection of modules has been described, and mention
cabal.projectconfiguration commands, syntax, and multiproject management. Here, we could add some content regarding remote source repositories like git.
- Testing a project
- Benchmarking a project
- Profiling a project
- Working with extra-build-tools and the more exotic parts of the
- How to package a project and work with Hackage to release
The goals of this project, in my opinion, should achieve the following:
- We want a quick reference to cite to beginners for getting up and running with a project that prints “Hello, World!” in as few commands as possible.
- We want a user-guide that can serve as a hand-holding exercise for beginners and more casual haskellers, who can follow along with a relatively simple, contrived project that slowly builds up some complexity into something publishable by the end.
- We want to delineate best practices for maintaining a cabal file, so that there is less confusion
- We want to show people how to publish and release.
- We would like people to walk away with a general understanding of how to do the most fundamental aspects of project maintenance, ranging from module additions, to testing, benchmarking, and profiling, as well as an understanding of how to work in general with dependencies, bounds, and remote source repos.
- We should aim to be as friendly and high level as possible, while also achieving these goals.
I’m interested to hear from @JonathanLorimer, @Mikolaj, @fgaz, @gbaz, and anyone else who has time to hash out an outline for this book. I’d love to have a public record here of our discussions for posterity.