Proposal: intermediate level, guided tutorials

159 views
Skip to first unread message

Michael Snoyman

unread,
Feb 18, 2015, 12:18:03 AM2/18/15
to commerci...@googlegroups.com
As some of you may have seen, I published a blog post yesterday[1] giving a detailed tutorial of primitive operations in Haskell, with the ominous warning:

> I'm going to be starting up a similar effort to Mezzo Haskell in the next few days, and I wanted to get a little more attention on this content to get feedback on style and teaching approach. I'll be discussing that new initiative on the Commercial Haskell mailing list.

Well, now's that time :). I've put the proposal on the commercialhaskell repo at:


As a summary, what I'm proposing is:

* We come up with a standard format and location for lots of documentation
* We get as much contribution as possible
* Those inclined to do so can curate that mass of content into whatever outlines they wish to focus on different topics
* Likely, this group itself will try to create an "Intermediate Haskell" book via one such outline

I've already written some content that's scattered around various places that I'd be happy to contribute to this effort, and I'm guessing others do. For the missing pieces, I believe that having a centralized place to request new content will inspire others to produce quality stuff.

Look forward to hearing some feedback on this idea.

thegravian

unread,
Feb 18, 2015, 11:18:04 AM2/18/15
to commerci...@googlegroups.com
I think the proposal makes some good points regarding quality and discoverability of documentation.  The proposal brings this up somewhat in the bit about searching for monad tutorials, but I wanted to emphasize this wrinkle with regards to discoverability/quality that might be worth putting some cycles into.  

I've found it challenging to map the "lexicon" of an imperative programmer to that of a Haskell programmer.  For example, a good, canonical C implementation of an algorithm may bear no resemblance to a good, canonical Haskell implementation (no surprise, right?).  A programmer may think they should use a Vector for an algorithm because they used one in Java, but is that really what they need to do in Haskell?  How can we help guide new programmers who may not be aware of the existence of critical language features that could make their lives easier (and implementations vastly better)?  Additionally, helping newer Haskell programmers make use of "more advanced" features instead of reinventing the wheel would also be awesome.  I don't know how many times I reinvented folds when I started writing Haskell.  It's easy to get a solid kernel of Haskell figured out, and then ignore some other big, important parts.

It can really be challenging to motivate the learning of a feature to a person who's never been exposed to the concept.  Monads aren't the only thing that are a sticking point like this.  Functors, applicatives, folds, and traversals are all useful things that can seem really foreign to learn, and can be "naively avoided" by the novice programmer.

I don't feel like I have a good answers to these questions right now.  Perhaps we could have "case studies" where we refactor  Bad Haskell into Good Haskell?  Something like "Hey, have you been writing code like this?  Well, you need to be writing code like THIS instead."  I'm sure I've missed some good work in this area.  Would love to hear the thoughts of the community on this!

--
You received this message because you are subscribed to the Google Groups "Commercial Haskell" group.
To unsubscribe from this group and stop receiving emails from it, send an email to commercialhask...@googlegroups.com.
To post to this group, send email to commerci...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/commercialhaskell/CAKA2JgL8QaygoXOAyTkZx%2Bdz_RxH66Uuk-vdOXnC6LDWOcJiqQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Michael Snoyman

unread,
Feb 19, 2015, 12:56:48 AM2/19/15
to thegravian, commerci...@googlegroups.com
I'm actually hoping that the "outline" part of this proposal addresses a lot of the concern here. Using traversals as an example: many people reinvent (or don't use) traversals because they don't know they exist. If we put it in the outline, and have a well written chapter demonstrating how to use it, I think it can help things out quite a bit.

That's not to take away from the ideas you brought up. Case studies, cookbooks, etc, are all wonderful content that I hope gets included as well. Generally, we should try to attack a problem in different ways, as different people learn things quite differently.

Jesús González

unread,
Feb 19, 2015, 1:24:40 PM2/19/15
to commerci...@googlegroups.com, mic...@snoyman.com
I tweeted an idea and @fpcomplete though I should share it in the forum.

The 2 tweets said:
"What if instead of unserialized tutorials/documentation, we could have a sort of knowledge dependency graph."
"Some textbooks have a graph where it says which chapters you need to understand in order to understand each chapter."

The problem I see with the concept "intermediate level" is that it is still hard to define well your audience. It's better than nothing, but I think we can do better.

I think that we should write knowledge (e.g. tutorials) as we write code, meaning: when should clearly define the knowledge dependencies of a given tutorial. This would precisely define the target audience of a given tutorial, as the tutorial should assume that the reader knows only what is declared in the tutorial dependencies.

Then, we could think of our body of knowledge as a DAG, where each node is a knowledge unit (set of inseparable concepts) that formally declares the nodes the user should priorly understand and the concepts it will introduce.

A good unit of knowledge should, as a good software module, rely on as few dependencies as possible.

Similar concepts are:
 - The one I mentioned in the 2nd tweet of a book that included a graph that indicated which chapters were necessary to understand in order to understand each chapter.
- Code Academy's tracks.
- Code. Each package declares its dependencies. I don't think we could use code directly as knowledge units since it is not always written with easiness of readability (performance and other constraints prevent this) and it doesn't always reflect reality well (e.g. Monad not being a subclass of Functor)

Michael Snoyman

unread,
Mar 3, 2015, 2:09:29 AM3/3/15
to commerci...@googlegroups.com
I've created a new repository for this effort at:


I've put my thoughts on how it should be run into the README.md file. I've also started copying in some of my existing content, and put together an outline for what I'd consider a good "intermediate Haskell" outline:


At this point, I'd like to try and "kick the tires" on this process and get things moving. I can see three places to get started:

* Write raw content
* Write a separate outline that is *not* focused on intermediate level stuff, but something else entirely, to demonstrate that this repo can and should be multi-purpose
* Provide feedback on the process described in the README overall

Like I say in the README, commit access to this repo should be given out freely, so if someone wants to get involved, just go for it, no permission needed.
Reply all
Reply to author
Forward
0 new messages