Make it clear Pursuit is the place for documentation

[marick]

(I couldn't find a better place to leave this comment - sorry.)

When I started learning Purescript, I wanted to find that place that documented all the "obvious" modules. The equivalent of Elm's http://package.elm-lang.org/packages/elm-lang/core/latest/ or https://hexdocs.pm/elixir/Kernel.html for Elixir. There was no obvious pointer to it. It was really just a guess that led me to try Pursuit from http://www.purescript.org/learn/. The text about Pursuit made it seem like (only) the package manager search site: the equivalent of http://package.elm-lang.org or https://hex.pm/packages or https://clojars.org -- not the place to find information everyone should know.

[hdgarrood]

This is definitely a good place to discuss this, thanks for opening an issue :)

Could you possibly expand on what you mean by "obvious" modules? I'm not quite sure I follow. Also could you give an example of what you have in mind in terms of information everyone should know?

[marick]

In Elm, there's the Basic package http://package.elm-lang.org/packages/elm-lang/core/latest/. In Elixir, there's the Kernel package https://hexdocs.pm/elixir/Kernel.html I have easy-click bookmarks for both of those. I click on them a lot. Prelude is the same thing, I guess, but compare the difficulty of (1) finding the documentation, and (2) navigating through it to find information on, say, "how to add an element to a dictionary".

(I just tried it. Once you discover that Pursuit is the place for documentation, you have to guess that Purescript's name for "Dictionary" is "Map". Then when you type "Map" into the search box, the actual purescript-maps result is the 8th one in the list. Importantly, that's past the bottom of the browser window on my macbook pro.)

More specifically, I think that all documentation for lists, arrays, dictionaries, Maybe, Either, and Functor should be at most two clicks away from the newbie's bookmark bar. Moreover, to be helpful to newbies, type classes like Functor should have their functions' documentation pulled down into the documentation of types like Lists, etc. (assuming Prelude is imported, because, really, it always is, right?) OO documentation is a good model: it tends to document subclass methods even when it could say "go look in the superclass" or (worse) "we won't mention X because you should know that it's documented in the superclass". It's also important to document "superclass" method behavior even when it's obvious. Tuple and Either are examples. If you think about it, it makes sense that map applies to the rightmost value of such types: but it would help novices a lot if (1) the actual behavior were documented and (2) they were pointed to an explanation of why the behavior makes sense.

There's an experience GUI app programmers are sometimes subjected to: they watch, forced to be silent, while newbies try to use the app. It's almost invariably enlightening and humbling. It would be very interesting to arrange that sort of fly-on-the-wall experience for Purescript documenters.

But that raises the question: "who is a newbie"? It should not be a Haskell programmer, I think: that makes Purescript a niche within a niche. I see two choices:

1. Someone coming to Purescript completely innocent of static FP languages. I think that's a very big leap, in no small part because of terminology (and the associated point of view). See https://twitter.com/Gankro/status/833383687668514816

2. Learning a less overwhelming language first. At one point, I thought that Clojure or Elixir would be that language, but I no longer think so. It's too big a jump. I've now tentatively concluded that Elm is a good intermediate step - so I don't think it'd be a bad idea to position Purescript as the next step beyond Elm.

I mention this because the most important part of writing documentation is being clear about what you think your intended audience already knows (and then how you'll deal with the fact that some of your actual audience doesn't know some of that).

I'm semi-committed to the Purescript-via-Elm path, so I'm willing to put some effort into that approach.

[hdgarrood]

Pursuit is really a place for library documentation, chiefly reference-style (i.e. for people who are already somewhat comfortable with the language). I don't think we should be pointing newcomers there, at least not until they've done a bit of introductory reading and/or exercises. The canonical introduction is PureScript by Example, which does not assume previous FP experience - before I respond to your points I just wanted to check whether you aware of it? https://leanpub.com/purescript/read#leanpub-auto-about-you

You are right that a guide on parametricity and why the Functor Tuple instance is the only possible one would be a very good thing to have. PS by Example touches on it but doesn't go into too much detail. I think right now the best thing we can do is point people to docs from the Haskell ecosystem as the principle works in the same way in Haskell.

[marick]

I'm working through the purescript book. (I'm pretty scrupulous about doing exercises.) However, it's not a good reference for when you want to try things on your own - like exploring how Tuples work. I think my point is that (1) there is no good reference, and (2) it's actually fairly hard to discover the best reference that exists.

Elixir is I think a good model to adopt. Module documentation begins with a general explanation (easily skippable by those who already know it). Here's the documentation for Tuples: https://hexdocs.pm/elixir/Tuple.html#content

Also, Elixir documentation encourages including examples in function definitions. Many people learn best by generalizing from examples. (I think accepting that will be important for the success of languages that have historically appealed to people who really dig the definition-theorem-proof style of math education. Which I did, once.)

I think Elm's documentation is weaker than Elixir's, but they have an interesting idea: module functions aren't documented alphabetically, but rather in groups, with the more useful functions coming first. That's pretty helpful for first-timers, at the expense of making it a bit more awkward for experts. (I think they could easily fix that by adding an alphabetical list in a sidebar.)

[hdgarrood]

Right, I see what you mean, thanks for expanding!

Elixir is I think a good model to adopt. Module documentation begins with a general explanation (easily skippable by those who already know it). Here's the documentation for Tuples: https://hexdocs.pm/elixir/Tuple.html#content

I'm definitely in favour of including more documentation of this style in the libraries like Tuple and Maybe. :+1:

Currently I think functions come out in Pursuit docs in the same order as they are listed in the export list in the source file, but if not we're going to change it to do that at some point.

[marick]

Elm does a vaguely literate-programming thing (I hereby invoke Knuth in an appeal to authority) in which the module source explicitly describes what amounts to the table of contents:

# Setting up an animation
@docs State, subscription, Msg, render
# Creating an animation
@docs interrupt, queue, Step, wait, to, toWith, toWithEach, set, repeat, loop, update, style, styleWith, styleWithEach, Interpolation, spring, easing, speed
# Animatable Properties
@docs Property, opacity, Length, top, left, right, bottom, width, height, padding, paddingLeft, paddingRight, paddingTop, paddingBottom, margin, marginLeft, marginRight, marginTop, marginBottom, color, backgroundColor, borderColor, borderWidth, borderLeftWidth, borderRightWidth, borderTopWidth, borderBottomWidth, borderRadius, borderTopLeftRadius, borderTopRightRadius, borderBottomLeftRadius, borderBottomRightRadius, shadow, textShadow, insetShadow, display, inline, inlineBlock, flex, inlineFlex, block, none, listItem

https://github.com/mdgriffith/elm-style-animation/blob/3.5.4/src/Animation.elm

[hdgarrood]

To address some of these points, I've done the following:

• The Getting Started guide now links to Pursuit at the end and suggests it as a next step for learners (#112)
• Doc-comments for instances will be displayed in the HTML documentation (after the next compiler release) https://github.com/purescript/pursuit/issues/159 - this includes a lot of stuff which will be helpful to beginners for understanding instances of classes like Monad and Alt for data types like Maybe and Either.

We also have the following issues which address points brought up here:

• Allow specifying a structure for docs https://github.com/purescript/purescript/issues/2525
• List of core libraries on Pursuit https://github.com/purescript/pursuit/issues/326
• Prioritise results from core libraries when searching https://github.com/purescript/pursuit/issues/327

Other than that I think it's just expanding these docs to make them more accessible to newcomers, which is ongoing work, so I think this can be closed. Thanks for writing it all up!