haskell-lang / haskell-lang

haskell-lang.org website

Deprecated. Please instead use:

https://github.com/fpco/haskell.fpcomplete.com

haskell-lang's Issues

Normalize domain names

Currently, both www.haskell-lang.org and haskell-lang.org are valid for accessing the site. Ideally, one of those would simply redirect to the other. I don't have much preference one way or the other being the primary domain name. @chrisdone @borsboom thoughts?

stack build in tutorial fails

in Get Started https://haskell-lang.org/get-started the quick tutorial suggest to build a new-project; but it fails with this error:

$ stack build
Invalid package ID: "array-0.5.1.1 base-4.9.1.0 binary-0.8.3.0 bytestring-0.10.8.1"

i have a fresh linux mint 18.1 install (installed another bunch of packages but with no manual configuration) and lts-8.2

this is my first time ever using issues on github; i apologize for any inconvenience or missing information

Difference between haskell-lang/haskell-lang and haskell-infra/hl?

Probably an early bird question that is coming too soon, but what's the motivation for splitting haskell-infra/hl into an organization of its own? Are there re-implementation plans or something similar? I'm asking because I'm trying to figure out which one I should be forking right now.

Clarify easy content contribution

Have clear content areas of the repo and make it really easy to contribute

• Everything is Markdown
• Package tutorials
• Fork this page

We can tie all this up by updating the README to cover key contribution areas, and having a standard place (probably static/markdown/) where all content contribs go.

Exception safety doc improvements

Nice doc so far! Below are up to discussion - recently I dig deep into exceptions, and having these points clean upfront would have helped save some time:

1. Maybe: provide guidance to make long-to-take allocation functions explicityl interruptible (in spirit of 1). So async timeouts can take effect on them (even though a long operation is likely to have interruptible operations on its own, for example since they do some network requests, etc). Note that interruptible is now is base since GHC 8.0.

2. Fine detail, but to avoid surprises: document that there's an important semantic change in allowInterrupt from GHC 7.10 to 8.0 (see 2) - in the latter being in Uninterruptible state doesn't allow interrupts to come through at allowInterrupt, while in 7.10 it does (as noted in 1). This means in GHC 7.10 cleanups which have allowInterrupt somewhere (or unsafeUnblock) can still throw, even if in Uninterruptible state.

3. Maybe: provide guidance on how to workaround blocking long in cleanups if they are uninterruptible by using safe-exceptions or by manually wrapping. Blocking long in cleanup might need to take long - for example if we want to attempt a clean shutdown of a connection in case some (app level) error. Maybe the cleanup could be forked to a separate thread with forkIOWithUnmask to be performed asynchronously, if that's acceptable.

4. Not sure what to do with the info, but deadlocking on an MVar in uninterruptibleMask (say newEmptyMVar >>= takeMVar) still seems to trigger the deadlock exception (see note about "Point 1" in 3). Might be surprising for some (but might also be a bug - not sure what the RTS should do).

Haskell Packages a bit confusing

Maybe this is just me. But I though I'd leave a comment here. Looking at the packages page:

• Why is QuickCheck in Core instead of Common/Testing? What is the differentiating factor between both? And why is on in Core and the others are not?
• Why not mention doctest, it might be a lesser known option in the haskell community, but for those coming from python, this might seem very familiar (apart from aiding documentation, by embedding examples).
• Why is haddock not mentioned? I'm looking at the packages page and wonder: what would I use for building documentation? (Maybe put haddock and doctest into Common/Documentation?)
• I'm also a bit confused about criterion in the list of Core instead of say Common/Benchmarking.

Docs classfication

We split up/or categorize the docs as follows:

API docs, books, tutorials, community resources, papers

• API documentation => this goes to the Packages section
• Learning materials
• References
• Community resources
• Papers

We can have a breadcrumb for each.

Improve "Features" blurbs?

I read through the "Features" part of the homepage that we inherited from haskell.org, and I'm not a fan of the writing style or the content. Would you guys agree?

If we want to improve this section, there are a few questions to discuss:

• Do we want to keep the "Features" section of the homepage?
• If so, do we want to keep the same 6 features, or change them?
• Once we choose which features we want to display, can we improve the blurbs?

---

Here are some of my opinions about the Features section:

• I dislike the writing style. I could give sentence-by-sentence critiques, but I think now is too early for that. We should discuss the first two questions above before discussing the third.
• The laundry list of packages is overwhelming and doesn't seem to have a particular purpose. The purpose of this section should be to demonstrate the breadth of libraries available in Haskell, so that programmers know that Haskell is a "real" language with solid ecosystem and libraries. I suggest the following:
  • To make the list less overwhelming, group the libraries by category. Maybe use some of the following categories: Networking, Web development, Systems, Streaming, Graphics, Parsing, Testing.
  • Remove bytestring, vector, text, etc. from the list. In my opinion, showing off that your language has a string library and a vector library doesn't impress new users.
  • Bias towards libraries that are surprising. Most languages have libraries like process, directory, time, etc. Let's show people libraries that make them think, "Wow, I had no idea you could do that in Haskell!" Maybe some of the following: graphics, numerical computing/parallel computation, concurrency, networking, web frameworks, GHCJS, etc.
  • Maybe emphasize the libraries that are unique to Haskell/hard to do in other languages. The ones that come to my mind are parsing, streaming, STM, QuickCheck, DSLs for HTML/CSS/etc.
• Maybe, instead of advertising features, we should advertise benefits: Avoid runtime/type errors! Generate high-performance, concurrent code! Reason about your code more easily! Refactor code easily!

Script for installing stack

As on this page, we need a script for installing stack:

https://ci.haskell-lang.org/get-started/osx

It should:

• Figure out the platform
• Download the right executable
• Add to the PATH ~/.local/bin

Tutorial/library page improvements and dedupe

• Unify the codebase between the tutorials and the library pages
• Add a "Discuss on Reddit" link next to the Github link
• Add a "Share on Twitter" link next to the Reddit link

Improve locally hosted tutorials titles

Hi,

In the documentation page, I think title for the packages' tutorials could be improved.

For example : "How to parse and encode JSON" instead of "aeson library" or "How to send HTTP requests" instead of "http-client library". What do you think? It will be much easier for a new haskeller to visually parse the links and find what it needs.

Improving the front page

Sharing feedback from a beginner to Haskell:

Initial feedback

From the perspective of a newb, https://haskell.org seems to have a helpful landing page while https://haskell-lang.org has a better "Getting Started" section. (edited)
https://www.haskell.org/downloads is certainly not helpful at all (edited)
I also wouldn't have noticed the two sites if it weren't for this discussion

explaining why they preferred haskell.org's front page

The try-it section, and the part with snippets mostly
Rather than describing things it shows a beginner how it actually looks
haskell-lang looks more noisy with the text, it would be nice to have descriptions mixed with code and include the try-it part
Videos don't matter much to me, but might to some

My thoughts

I think haskell.org's front page has a bit more flash at the moment, it's possible the designer I retained to do that work exceeded his mandate 😛

Add a purpose statement on r/haskell_lang

In the recent discussion threads on Hacker News and r/haskell about haskell-lang.org there has been some confusion on the purpose of the new r/haskell_lang subreddit.

It would be good to add a short paragraph on r/haskell_lang that explains the purpose of the subreddit. For example:

This subreddit is intended for discussions and questions regarding the haskell-lang.org website.

404 Not Found after following the QuickCheck link from haskell-lang.org/packages

Steps to reproduce:

• go to https://haskell-lang.org/packages,
• click on the link for quickcheck.

Expected result: The quickcheck Stackage page should be loaded (I used the search on the main page of Stackage and found this: https://www.stackage.org/package/QuickCheck).

Actual result: https://www.stackage.org/package/quickcheck is loaded, saying that something was "Not Found", with the according HTTP response status code.

Idea: Create a search bar (on the main page?) that is aimed at beginners

I wish haskell-lang.org had a search bar that would allow to search for

• library functions, types, etc.,
• package names,
• keywords
• and probably some miscellaneous things like main concepts and terms.

The main goal is to create an easy way for beginners to discover the language. This idea is probably best explained through some examples:

search terms	first search results
map, filter, String	Links to the respective haddocks
quickcheck, lens	Links to the package pages
import, "if then else", newtype	Relevant wiki articles, other good explanations
laziness, currying, "type classes", exceptions	Relevant wiki articles, other good explanations
"for loops", "while loops", goto	Links to explanations that these don't exist and why and how to program without them

(Ok, "goto" is a joke.)

I've looked into kotlin today and its website provides a search bar similar to this that I found immensely useful.

Maybe approximation of this could be implemented on top of hoogle and google's site: feature.

HTTP server libraries

I think the libraries page could use something related to web servers - should Warp be on the list?

Tutorial pages per package

Mentioned in #27

We'll have a /tutorial/package-name route. This page will be fed in from a markdown file (maybe /static/tutorial/package-name.md?). If that page exists for a package, then a link to it will automatically be generated on /packages.

Very low speed in mainland China

I don't know if any one call out this.

1. it will take around 50minute to down load stack-installer.
   I think that is cause by AWS slow link speed (Amazon want you spend more money?)
   compare to Hackage very fast and at acceptable speed.

2. on the web page there is also load a google file. that can not diret link in China
   that will bring down the load speed.

Above is a ture experience in China. I don't want to bring any policitcal judge for any one.

Native GUI Section

On the Libraries page I was thinking that a Native GUI section might be helpful since people do seem to ask about that. If that's ok, I'd like to submit a PR to have FLTKHS added to it. Thoughts?

Fix the downloads page

We need to:

• Present one clear download solution.
• Maybe have a few steps with a sample project to get started?

This could be part of or merged with the Getting Started page.

Pinging @bitemyapp @snoyberg @OldManMike

List of editor integration guides

In the documentation section, let's have an editor integration section.

We can list the common ways to get editor integration, and consult the relevant people for the proper way to do it for a given environment.

• Emacs
• Spacemacs
• Vim
• Sublime
• Atom
• etc

Automated link checking

It would be good to have, as part of a Travis build, automated link checking.

Remove `stack hoogle` feature from Get Started page until it has been properly released

I think the current state of the page gives the impression that stack hoogle has already been released.

Better "next steps" tutorials for "Get started" page

I was discussing with @bitemyapp, and it seems like we have some room to improve the "Next steps" in the get started page with targeted usage tutorials. We identified three different common use cases we could see addressed:

• "How to play": tutorial on using Stack+GHCi to experiment with code
• "How to script": tutorial on using stack runghc to write short programs
• "How to build a project": tutorial on Stack's more powerful feature set around stack new, stack build, etc

It might make sense to have these three as their own Stack tutorial section (with a link "learn more at haskellstack.org"), and then a fourth section for "what's next."

Make a VISION.md document

In which we can pop down the core goals of the site. Something like:

• Target both newbies and experts alike.
• We will target newbies by helping them find:
  • Tools that they need
  • Learning materials that they need
  • Providing helpful overviews of common most packages
• We will target experts by catering to expert use-cases, like package/API documentation
• We'll ensure that both crowds are interested in the "well-being" of the web site in terms of being up to date and useful, by making it useful for both crowds, as written above.

Restyle related sites to match haskell-lang.org

At the very least we should have a link to Stackage prominently on the site for discovering packages and browsing their documentation. But there are likely other sites that should be included as well.

Suggestion: Friends Page

Similar to the Friends of Rust Page that showcases companies using Rust and their use case. I think this would be pretty cool. Not sure how I should approach implementing it though. I don't want to just statically type it all. I think that would be bad for page loading speed. Any suggestions?

Wrong (non-Haskell) code and table layout

Looking at https://ci.haskell-lang.org/package/aeson, I'm noticing that the GHCi and table mark-up didn't get converted to HTML properly. The table markdown just gets put into a p element, while the non-Haskell code is just inserted as it is.

IRC and Mailing list page gives Internal server error

IRC: https://ci.haskell-lang.org/irc
Mailing list: https://ci.haskell-lang.org/mailing-lists

Error:

hGetContents: invalid argument (invalid byte sequence)

It does work locally.

Make an example of running a process

Experience shows us that clients and newbie Haskellers generally need to figure out how to launch a process, it's not obvious. So let's include an example out of the box for that which uses the process package.

Operator Glossary is missing <|>

Hi,

if I'm not wrong the "Operator Glossary" page is missing <|> defined in Control.Applicative for the Alternative class.

HTH
walter

Q: License for content on http://haskell-lang.org?

I see that the top-level LICENSE file places this Git repo under BSD3 terms. Does this also apply to the documentation/tutorials that are currently worked upon? I'm asking because those are looking quite useful and I'm considering integrating parts into teaching material of mine. In order to do that, some level of legal certainty would be desirable. Hence this question. Do you plan to stay with BSD3 terms for the content?

Clarify purpose of /r/haskell-lang

In relation to: https://www.reddit.com/r/haskell_lang/comments/4rv4uu/is_this_the_official_haskell_subreddit_or_is/d54cpja

This should be reflected both in the sidebar of subreddit as well as in the announcement post.

Conduit library description actually describes vector

Hello,

https://haskell-lang.org/library/conduit appears to be describing the vector package instead of conduit.

Regards,
Bence Kodaj

Finding relevant documentation via search engines is incredibly difficult

It is difficult to find relevant haskell documentation with search terms. This was briefly discussed on twitter https://twitter.com/Blaisorblade/status/825082970495135744

Fixing this would allow for newcomers to easily find information, enabling them to learn more about the Haskell ecosystem.

There are some SEO tricks that we can do to fix this.
I'll come back to this issue tomorrow to fill it out further

1. Remove dead/broken links.
   Dead/Broken links greatly reduce SEO ranking. We can use google analytics to see all the broken internal links (https://support.google.com/webmasters/answer/138752?hl=en) or some other tool.
2. Add Metadata
   HTML metadata or JSON-LD metadata would help with indexing content
   https://support.google.com/webmasters/answer/79812?hl=en
3. Add descriptions of content (Abstract or summary) in meta tag
   https://yoast.com/meta-descriptions/
4. Add a sitemap (include out of date content with appropriate tags)
   https://support.google.com/webmasters/answer/156184?hl=en
5. Add no-follow to external links
   https://support.google.com/webmasters/answer/96569?hl=en
6. Add publish dates to content

This is a huge goal. Achieving this would greatly increased visibility and ease adoption of the Haskell language.

Intero recommendation on downloads page seems out of place

The downloads page is light and crisp. It advertises haddock/stack/ghc - all things which no modern Haskeller can be without, and all of which are stable and production ready beyond a shadow of a doubt. It also advertises Intero, which as far as I can tell, is Emacs only, much newer, and still under heavy development. I worry the Intero advert confuses the issues, and sends people down a route where many will ultimately not be happy (e.g. "urgh, i have to use Emacs for Haskell development") - while also brushing over lots of widely used alternatives (e.g. Leskah, haskell-mode, SublimeHaskell).

I'm not doubting the quality of Intero, it certainly seems pretty awesome, I just don't think it fits well with the rest of the set.

Replace primes on the homepage with real examples

Replace primes on the homepage with a snippet of a complete example, click it to view the whole thing.

• Show a random example each time they load it up.
• Include an example of each of the main packages (vector, bytestring, async, base, etc.)

With Stack we can provide samples that run out of the box.

Annotate the learning resources on the Documentation page with terse, useful summaries

Right now the Documentation page is a wall of links with no context given. Each link should should have something of like a short summary to inform a potential reader whether a resource is worth checking out. Summaries shouldn't be too verbose as to appear busy, just a terse description about what the doc covers. An example might be:

• Learn You a Haskell for Great Good:
  An illustrated book that covers the core features and syntax of the language itself, but assumes you know how to program already. Doesn't cover project setup, useful libraries, or how to approach non-trivial projects in general. Freely available online. No exercises.

Make a Getting Started page

It should:

• Show where to download Haskell.
• Show where to start reading a Haskell book.
• Maybe some other alt. free reading resources less prominent below.

We will link to it from the top of the page, and at the bottom as a funnel of where to go next after they've finished reading the page.

Help me decide

https://haskell-lang.org/libraries is great, but I want more!

On https://haskell-lang.org/libraries#_common_testing, I'd like links to articles that can help me decide between the options.

Some signals that could be relevant:

• An article explaining the differences
• Github stars
• Number of github issues, forks, authors.
• New projects in the last year depending on the library.
• "Famous" projects using the library
• Is the library in stackage nightly?

In the case of http client libraries, for example wreq is not in stackage nightly, which is a red flag wrt for example http-client or http-conduit (not listed).

To get this even more fancy, create a nightly job that created a .json file with the above information (all dependencies of all packages, list of defined 'famous' projects, which packages are in stackage nightly, github stats, date of first release). Then this data could be added all over the place.

Curated list of Haskell packages

First off, great initiative! Hopefully this can replace haskell.org instead of competing with it, but I'll leave that for another discussion.

---

From what I could gather about the project, one of the goals was to make the website a stop for newcomers where they could navigate how to learn Haskell.

One of my major gripes as someone a bit inexperienced still, but following the community closely, is that I often have a hard time finding out what the recommended packages are for certain things.

There are efforts such as http://haskelliseasy.readthedocs.io that try to offer a more opinionated list of packages for various purposes, and I think this would be something that a Haskell site could benefit from - either by linking to the aforementioned site, or by supplying a list itself.

If this is a bit off scope with the project or goals of the project, feel free to close the issue. Just thought I'd add what I've found hard to navigate in my own experience.

Support package tutorials from other sources

Specified in the YAML file with the package descriptions.

Reddit section within News is not updated?

Hello,

The entries in the Reddit section on the News page (https://haskell-lang.org/news) are a week old. Are there really no newsworthy Reddit entries since last week?

Regards,
Bence Kodaj

Add some tutorials from Jump docs

Since incorporating remote tutorial has been implemented, why not bring some nice tutorial from Jump: https://github.com/commercialhaskell/jump/tree/master/doc

I would specifically like the http-client and the command line parsing tutorial.

Papers repository

Since there are many papers about haskell that are useful to understand the language further it might be nice to have a repository where people can browse and search all papers. If paper license permit than be able to download paper too, else link to original source.

Detect the client plateform for Stack installation instructions

Hi,

I think it could be great to detect the OS of the visitor to reduce the huge list "Instructions for Windows, Mac OS X, Ubuntu, Debian, CentOS / Red Hat / Amazon Linux, Fedora, openSUSE / SUSE Linux Enterprise, Arch Linux, NixOS, Linux (general), FreeBSD (unofficial)". If the user agent is not correct, the visitor can still click on the general "View the full Stack installation page".

A little bit like the homepage of Rust (https://www.rust-lang.org/), one link "Install" and if the user agent is not correct "Other Downloads" but instead of the simple "Install", show a list of matching OS instructions.

I'm not sure it's possible to really reduce the list for Linux users (my ArchLinux just send Linux in user agent…) but at least for Windows and OS X.

Make /packages page

We make a /packages page (and in the nav) which shows:

• List of recommended packages (bytestring, text, vector, etc). Criterion:
  • Almost universally accepted as the right way to do it
  • Addresses common use cases
• Other common tasks with multiple options
  • E.g., tasty vs hpsec, conduit vs pipes
• Give some useful information on each, why you’d choose one or the other
• View all packages (link to https://www.stackage.org/lts)
• When relevant: include links to tutorials on the packages (self host on haskell-lang.org via the Jump project content?)

We also bring stackage.org/lts under /packages/lts, and style it as haskell-lang. Coupled with the restyled Haddocks, this brings everything (packages, haddocks, hoogle) under one user experience.

For the recommended packages, we have:

• Tutorial page per package (e.g., /tutorial/http-client) https://github.com/commercialhaskell/jump/blob/master/doc/http-client.md
• Include link to API docs
• Recommendations for writing docs: lots of examples, examples include Stack script interpreter lines

Add intero to "get started"

Intero has recently been added to the site - https://haskell-lang.org/intero (yay!)

Looking over https://haskell-lang.org/get-started, I believe adding intero to that page would make a lot of sense.. definitely in the "next steps" section, possibly also including a mention in the list of reasons why stack is great (you get to use intero!).

Remove videos from homepage?

I totally agree on what was said on #2 by @OldManMike.

There's a rather large CSS row dedicated to showcasing the "An open source community effort for over 20 years" along with links to meetup videos. When I was a new user, this would be wasted space. Most languages I was checking out where open source initiatives, so that's not much of a selling point and I wouldn't be particularly interested in watching meetup videos on Haskell topics before I even really know what Haskell is or why I should invest time in immersing myself in it. In fact, with the minimal synopsis in the branding header and the feature list being completely out of view unless I scroll down, the home page doesn't seem to be interested in telling me what Haskell ACTUALLY is. This is bad.

Moreover, the six videos are really old, they give an old picture of Haskell. So, should we remove the video section? Or at least move them from the homepage?

Some sort of RSS feed

I think it's pretty likely that we'd like to be able to announce things from this site via RSS, so having a feed would be a good thing. I don't think we'll want full-blown blog functionality, but the ability to mention that new tutorials are available, for example, would be good.