reubenharry / haskell-docs Goto Github PK

In particular:

• [] improve the style guide
• make reviews required
• make direct pushing to main forbidden

Currently, adding this plugin causes a crash, and I don't know why.

https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/

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

can you please release the code under a code-friendly license like the MIT license?

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.

Hi,

Including the website url the repo's link is a common place that users like myself look. It may not be so obvious that the giant h1 header is actually a link to the book website.

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.

Finish coding up a chess+repl Haskell example.

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.

https://squidfunk.github.io/mkdocs-material/setup/adding-a-comment-system/#giscus-integration

Motivation: allows users to ask questions / give comments where they don't understand, which in terms helps to improve the docs.

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

Instead of laboriously going through every common typeclass, just carefully explain how to read Hackage docs which show a typeclass.

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

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?

The link to the performance guide in Resources>Overview is broken. It’s now at https://haskell.foundation/hs-opt-handbook.github.io/