https://github.com/reubenharry/haskell-docs

https://github.com/reubenharry/haskell-docs

Last synced: 3 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/reubenharry/haskell-docs
• Owner: reubenharry
• License: cc-by-4.0
• Created: 2023-01-07T17:12:07.000Z (almost 2 years ago)
• Default Branch: main
• Last Pushed: 2024-01-10T14:13:30.000Z (10 months ago)
• Last Synced: 2024-02-17T10:37:24.003Z (9 months ago)
• Language: Haskell
• Size: 8.17 MB
• Stars: 56
• Watchers: 3
• Forks: 7
• Open Issues: 8
• Metadata Files:
  • Readme: README.lhs
  • Contributing: Contributing.md
  • License: LICENSE.md

Awesome Lists containing this project

README

        
# [The Haskell Guide](https://haskell-docs.netlify.app/)

This is the github repository for [an introductory guide to learning Haskell](https://haskell-docs.netlify.app/).

If you're interested in contributing to the guide, see [here](/Contributing.md) for more information.

## Goals

The goal for this project is to be a pathway into Haskell for newcomers who have programming experience in a language like Python. In other words, it should assume no knowledge of Haskell, and make it as effortless as possible to understand Haskell's core ideas.

With that in mind, it should be:

- **free and online**

- **maintainable**: just markdown, easy for anyone to update via a PR

- **ergonomic**: pleasing to look at and use, good search, easy navigation

- **friendly**: clear usage examples of code, FAQs and gotchas, pointers to other resources, unambiguous set up instructions for Haskell, contains an example project with best practices

- **concise**: avoids prose where possible

[Material for MkDocs](https://squidfunk.github.io/mkdocs-material) is a great platform for these goals. It's very easy for anyone to propose changes (click Edit icon on any page to submit PR), and is designed to display information well (info boxes, code comments, tabs, columns, automatic contents, and search for navigation).

## What's wrong with existing resources?

Well, nothing actually! There's a large range of great resources, both for beginners and intermediate Haskell programmers.

These resources often have quite different goals to The Haskell Guide, however. They (usually) aim to provide a complete introduction to Haskell, either to a coding beginner or a Haskell newcomer, and do so in a linear way (a series of written chapters, projects, or videos).

By contrast, The Haskell Guide is less interested in providing a didactically complete experience. Instead, it wants to get newcomers over the hurdles that traditionally make Haskell inaccessible. Removing these obstacles lets newcomers, who might have no reason to think Haskell is worthwhile, give Haskell a chance. Key resources for newcomers include:

- Simple examples of code doing simple practical things

- Concise examples of how the syntax works

- Concise explanations of why one might want to use Haskell (purity, algebraic types, etc)

- Steps to get oriented (installation, toolchain, ecosystem, core resources)

The Haskell Guide is founded on the hunch that removing these hurdles via a free, ergonomic, clear online reference guide could have a much bigger effect on Haskell uptake than even an extremely high quality book, which already requires buy-in from a newcomer.