Coder Social home page Coder Social logo

haskell-docs's Introduction

This is the github repository for an introductory guide to learning Haskell.

If you're interested in contributing to the guide, see here 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 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.

haskell-docs's People

Contributors

amalloy avatar amhuppert avatar cdsmith avatar isopropyletherperoxide avatar pennychase avatar reubenharry avatar simonmichael avatar soupi avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

haskell-docs's Issues

"Edit this page" link is broken

At the top of each page is an edit icon with the title "Edit this page". However, clicking on it leads to a 404 from GitHub, on a URL like https://github.com/reubenharry/haskell-docs/edit/master/docs/index.md.

Add "How to build a project"

It is very common that newcomers don't understand cabal nor stack project organization. I propose to create a file where we describe all sections in a .cabal file, linked to a reference project. The documentation for this should include:

  • what is a cabal/stack project
  • what is a package
  • what is a component within a package
  • differences between executable components and library components
  • differences between stack.yaml/package.yaml/cabal.project/<package-name>.cabal

I can contribute with this If you are willing to include it. The only detail is which section this information should be

Code checking and running

It would be nice if all the code mentioned in the docs is actually compiled, so that errors can be caught, and migration to new versions is easier. This would also help support multiple GHC versions: one could recompile with a different version, and quickly find out what breaks.

Tintin is a tool that does this, so it's clearly possible, however support for GHC-9 seemed to be lacking.

More ambitiously, it would also be nice to be able to run any of the code without leaving the site. This is maybe more possible with the advent of JS and WASM backends.

Regarding the target audience of the tutorial

It seems like this guise is geared towards for developers accustomed in python. I doubt this is appropriate audience to introduce haskell.

There is barely any reason that python enthusiasts would ever try out haskell.
Usually people learned python because it is easy to learn, haskell is the opposite of approachable.
Especially, the obstacles are on two fronts.
First, the strict and stringent type system would baffle them. Then, they would choke in the forced purity, as they are used to running action anywhere to get things done.
They also have nothing much to gain from haskell, as they are usually more interested in finishing the program as fast as possible without much concerns on safety.

So, why did you choose python developers as the target audience?

Make GHC version clear

It should be clear which GHC version is being used. Ideally you'd have this info shown on every page.

Discuss more packages

Examples and explanation of:

  • lens, lens-aeson
  • servant
  • pipes/conduit/streamly
  • log-domain (as example of newtype)
  • free (with a tree based example)
  • haskeline (or just reference in case study)
  • process or typed-process
  • diagrams
  • Yampa/dunai
  • QuickCheck
  • discrimination

Online code playground

A longer term goal. It would be really nice if the code snippets in the docs were runnable online and/or if HLS or Hackage style code highlighting was available.

With the advent of WASM and JS backends, this is something to think about.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    πŸ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. πŸ“ŠπŸ“ˆπŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❀️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.