Haskell Documentation blog post
This commit is contained in:
parent
e149097b40
commit
a6db4be540
2 changed files with 242 additions and 0 deletions
|
@ -1,3 +1,6 @@
|
|||
- file: posts/haskell-documentation-2016-update.md
|
||||
title: "Haskell Documentation, 2016 Update"
|
||||
day: 2016-11-28
|
||||
- file: posts/haskell-for-dummies.md
|
||||
title: "Haskell for Dummies"
|
||||
day: 2016-11-23
|
||||
|
|
239
posts/haskell-documentation-2016-update.md
Normal file
239
posts/haskell-documentation-2016-update.md
Normal file
|
@ -0,0 +1,239 @@
|
|||
I've blogged, Tweeted, and conversed about Haskell documentation quite
|
||||
a bit in the past. Following up on
|
||||
[tooling issues](https://www.fpcomplete.com/blog/2015/05/thousand-user-haskell-survey),
|
||||
all available evidence tells me that improving the situation for
|
||||
documentation in Haskell is the next
|
||||
[obstacle we need to knock down](/blog/2016/11/spreading-the-gospel-of-haskell#attacking-haskell39s-flaws).
|
||||
|
||||
This blog post will cover:
|
||||
|
||||
* Where I think the biggest value is to be had in improving Haskell
|
||||
documentation
|
||||
* Status of various initiatives I've been involved in (and boy do I
|
||||
walk away red-faced from this)
|
||||
* Recommendations for how others can best contribute
|
||||
* A basic idea of what actions I - and others at FP Complete - have
|
||||
been taking
|
||||
|
||||
## Intermediate docs
|
||||
|
||||
In my opinion, the sore spot for Haskell overall is _intermediate_
|
||||
docs. (Yes, that's vague, bear with me momentarily.) I'm going to
|
||||
posit that:
|
||||
|
||||
* Beginners are currently well served by introductory Haskell books,
|
||||
and most recently by
|
||||
[Haskell Programming from First Principles](http://haskellbook.com/)
|
||||
* Once you have a solid basis in intermediate concepts, it's much
|
||||
easier to jump into libraries and academic papers and understand
|
||||
what's going on
|
||||
|
||||
To me, intermediate means you already know the basics of Haskell
|
||||
syntax, monads, and common typeclasses, but aren't really familiar
|
||||
with any non-base libraries, concurrency, or exception handling. The
|
||||
goal of intermediate documentation is to:
|
||||
|
||||
* Teach _which_ libraries to use, _when_ to use them, and _how_ to use them
|
||||
* Give a guide on structuring Haskell programs
|
||||
* Educate on important techniques, including those mentioned above, as
|
||||
well as issues around lazy evaluation and other common stumbling
|
||||
blocks
|
||||
|
||||
Many of us who have learned Haskell over the past many years have
|
||||
probably picked up these topics sporadically. While some people will
|
||||
want to plow ahead in that kind of haphazard approach, my belief is
|
||||
that the vast majority of users want to be more guided through the
|
||||
process. We'll get to the Haskell Syllabus and opinionated vs
|
||||
unopinionated content a bit later.
|
||||
|
||||
## Previous efforts
|
||||
|
||||
It turns out, as I'm quite embarassed to admit, that I've essentially
|
||||
tried reinventing the same intermediate docs concept multiple times,
|
||||
first with
|
||||
[MezzoHaskell](http://www.yesodweb.com/blog/2012/03/start-mezzo-haskell),
|
||||
and then with
|
||||
[the Commercial Haskell doc initiative](https://groups.google.com/d/msg/commercialhaskell/Ou00AvRdDTU/7BtgTUrTSCQJ). You
|
||||
may also include [School of Haskell](https://www.schoolofhaskell.com/)
|
||||
in that list too, but I'm going to treat it separately.
|
||||
|
||||
These initiatives never took off. A pessimistic view is that
|
||||
Haskellers are simply uninterested in contributing to such a shared
|
||||
body of intermediate-level docs. I actually believed that for a bit,
|
||||
but recent activity has convinced me otherwise. I think these previous
|
||||
initiatives failed due to an unsatisfactory user experience. These
|
||||
initiatives required people to go to an infrequently used Github repo
|
||||
to view docs, which no one was doing. A few months back, a new option
|
||||
presented itself.
|
||||
|
||||
## haskell-lang's documentation
|
||||
|
||||
For those who haven't seen it, you should check out the
|
||||
[libraries page](https://haskell-lang.org/libraries) and
|
||||
[documentation page](https://haskell-lang.org/documentation) on the
|
||||
[haskell-lang.org](https://haskell-lang.org/) site. I believe this
|
||||
hits the nail on the head in many different ways:
|
||||
|
||||
* It directly addresses a common user question: which are the best
|
||||
libraries to use for a certain task? The libraries page gives this
|
||||
answer (though it can certainly be improved and expanded!)
|
||||
* We're able to curate the documentation as a community. Providing a
|
||||
list of recommended documents on this site gives a reader more
|
||||
confidence than simply Googling and hoping the author knows what
|
||||
he/she is talking about
|
||||
* The collaboration is done via pull requests on markdown files. I've
|
||||
[discussed previously](http://www.yesodweb.com/blog/2015/08/thoughts-on-documentation)
|
||||
why I think this is a far better collaboration technique than Wikis
|
||||
or other options.
|
||||
* Instead of requiring all docs live within the haskell-lang.org
|
||||
repository, documents can be embedded from elsewhere. For example,
|
||||
I've
|
||||
[written a conduit tutorial](https://github.com/snoyberg/conduit#readme)
|
||||
in the conduit repository, and
|
||||
[embedded its content on haskell-lang.org](https://haskell-lang.org/library/conduit)
|
||||
via
|
||||
[a simple inclusion mechanism](https://github.com/haskell-lang/haskell-lang/blob/master/static/tutorial/package-conduit.url). This
|
||||
allows authors to maintain their documentation individually, but
|
||||
provide users with a central location to find these kinds of
|
||||
documents. (I'd encourage other sites to take advantage of this
|
||||
transclusion technique, getting quality content into user hands is
|
||||
the goal!)
|
||||
|
||||
haskell-lang tries to host only "uncontroversial"
|
||||
documentation. Documents explaining how to use a library are pretty
|
||||
straightforward. Recommending libraries like bytestring, text, and
|
||||
vector are all pretty well accepted. And for cases where multiple
|
||||
libraries are used, we link to both.
|
||||
|
||||
I've merged all of the content I wrote in MezzoHaskell and the
|
||||
Commercial Haskell doc initiative into haskell-lang.org where it
|
||||
fit. However, there was still some more controversial content left,
|
||||
such as
|
||||
[exceptions best practices](https://www.fpcomplete.com/blog/2016/11/exceptions-best-practices-haskell),
|
||||
which I know many people disagree with me about. Also, I'd like to be
|
||||
able to tell a user looking for a solution, "yes, there are multiple
|
||||
libraries around, I recommend __X__." Neither of these belong on a
|
||||
community site like haskell-lang, so for those...
|
||||
|
||||
## More opinionated content
|
||||
|
||||
This is where alternative sites thrive. Since I'm collaborating with
|
||||
others at FP Complete on this, and actively using this in
|
||||
[training courses](https://www.fpcomplete.com/training), I've put
|
||||
together a
|
||||
[Haskell Syllabus page](https://www.fpcomplete.com/haskell-syllabus)
|
||||
page. This is where I'll tell someone "you should do X, even though
|
||||
others disagree with me." I won't enumerate the contentious decisions
|
||||
here (odds are someone else will ultimately make such a list on my
|
||||
behalf).
|
||||
|
||||
And if you disagree with this? Write a new syllabus! I think it would
|
||||
be a healthy thing if we could get to the point as a community where
|
||||
we could have multiple recommended, opinionated syllabuses, and link
|
||||
to them with a short description for each one. This may sound at odds
|
||||
with some of my previous statements, so let me clarify:
|
||||
|
||||
* When there's an obviously best choice, tell the user to use it
|
||||
* When most users will be best with one choice, and another option is
|
||||
available, mention it as a footnote
|
||||
* When multiple options are available and there's no way to know which
|
||||
the user will want, break down and give them all the information
|
||||
they need. But...
|
||||
* Try to make that happen as infrequently - and as late in the
|
||||
learning process - as possible! If we could have a "you've completed
|
||||
Beginner Haskell, please choose between one of the following," and
|
||||
explain the difference between "FP Complete's course" vs (for
|
||||
example) "lens-first Haskell", that would be a good trade-off.
|
||||
|
||||
My thoughts on this are still evolving, and will likely change in the
|
||||
future as I get more feedback from users.
|
||||
|
||||
## Writing style
|
||||
|
||||
Another big change I've made over the years is writing style. I wrote
|
||||
the Yesod book in a very prose-heavy manner, focusing on explaining
|
||||
details with words, and using concise, to-the-point code
|
||||
examples. Many users have given me feedback to push me in a different
|
||||
direction. Instead, I've recently been writing trying to write in a
|
||||
very different, and thankfully easier to write, style:
|
||||
|
||||
* Short explanation of what the thing is I'm talking about and when
|
||||
you'd use it
|
||||
* Synopsis: medium sized code snippet to give a flavor (I used this in
|
||||
the Yesd book too, and stole the idea straight from Perl docs)
|
||||
* A series of increasingly complex examples, with the bare minimum
|
||||
amount of content around it to explain what's going on
|
||||
|
||||
I'd put this style into a hybrid of tutorial and cookbook, and think
|
||||
it works well overall. I've only heard positives so far versus
|
||||
previous styles, so that's encouraging. Some examples:
|
||||
|
||||
* The
|
||||
[http-client tutorial](https://haskell-lang.org/library/http-client)
|
||||
fits this well, since there are no deep concepts to explain
|
||||
* [conduit](https://haskell-lang.org/library/conduit) has a bit more
|
||||
explanation, but is still mostly code examples
|
||||
* At the other end,
|
||||
[Primitive Haskell](https://haskell-lang.org/tutorial/primitive-haskell)
|
||||
and
|
||||
[Covariance and Contravariance](https://www.fpcomplete.com/blog/2016/11/covariance-contravariance)
|
||||
and much more concept-heavy, and therefore still have a significant
|
||||
chunk of prose
|
||||
|
||||
I'm taking this approach because I think it's what most users
|
||||
want. Some important points:
|
||||
|
||||
* Not all users are the same! There will almost certainly be users who
|
||||
would prefer a different style of docs. Given enough user feedback
|
||||
and manpower to write docs, it would be great to cater to all
|
||||
tastes, but it's best right now to focus on the highest demand
|
||||
* API docs are still necessary, and are completely orthogonal to
|
||||
tutorials. A tutorial doesn't document each API call, an
|
||||
API-call-level explanation doesn't give enough breadth, and
|
||||
certainly users need more than just the type signatures.
|
||||
|
||||
## What you can do
|
||||
|
||||
After all of that, my recommendation on how to get involved is pretty
|
||||
simple:
|
||||
|
||||
* Pick a library that doesn't have a good tutorial
|
||||
* Write a tutorial
|
||||
* Submit a
|
||||
[PR to haskell-lang](https://github.com/haskell-lang/haskell-lang#contributing-content)
|
||||
to include the content
|
||||
* Alternatively: get the Markdown file included in the project's repo
|
||||
instead, and include the remote file instead
|
||||
|
||||
## Linking to libraries
|
||||
|
||||
haskell-lang has a nifty feature. If you visit
|
||||
[https://haskell-lang.org/library/vector](https://haskell-lang.org/library/vector),
|
||||
it will display the vector documentation it has. But if you visit a
|
||||
package like
|
||||
[https://haskell-lang.org/library/stm](https://haskell-lang.org/library/stm)
|
||||
which doesn't (yet) have a tutorial on haskell-lang, it will
|
||||
automatically redirect you to the
|
||||
[Stackage package page](https://www.stackage.org/package/stm). When
|
||||
giving out links to people on the internet, I recommend using the
|
||||
haskell-lang.org/library/XXX link.
|
||||
|
||||
* When a tutorial is available, the haskell-lang page is great
|
||||
* When a tutorial isn't available, the doc building on Stackage is
|
||||
still the most reliable around
|
||||
* In addition, Stackage docs properly link to docs built in the same
|
||||
Stackage snapshot, making the cross linking more reliable
|
||||
* When present, Stackage gives preference to the `README.md` files in
|
||||
a package, which are generally more useful than the description
|
||||
fields.
|
||||
|
||||
## School of Haskell
|
||||
|
||||
I'd be remiss in not mentioning School of Haskell here. As far as I'm
|
||||
concerned, School of Haskell is great platform for an individual to
|
||||
write content without any collaboration. However, for all of the cases
|
||||
I'm describing here, some kind of easy collaboration (via pull
|
||||
requests) is a huge win. Opening things up more with pull requests,
|
||||
README.md files, and embedding content into multiple external sites
|
||||
seems like the best option today (until someone comes up with
|
||||
something better!).
|
Loading…
Reference in a new issue