We can absolutely agree on an agenda regarding the haskell.org documentation page.
Tutorials
As far as tutorial, I think we should be aiming for two complementary things:
- a 10’000-feet, all-encompassing overview (I have in mind something like https://docs.python.org/3/tutorial/index.html), ideally providing examples comparing Haskell code to non-Haskell code (i.e. Python/Javascript/C++), since most people coming to Haskell are likely to have some degree of expertise in other languages like these.
- a do-it-yourself, hands-on first tutorial in the strict sense of the word, something like this or that.
The point of (1) would be to show the ropes to non-Haskell programmers. The point of (2) would be to show the ropes to everyone. Together these two pieces can act like a robust introduction (with interactive elements thanks to the second one) to Haskell, preparing people to either start doing simple things or to pursue their learning path with more online material or books.
On the issue of having such tutorials, the main points to deliberate on (regarding either (1) or (2)) are as follows:
-
depth in contents or in presentation: do we layer the contents so that each audiences have their own relevant “layer”, with the adequate amount of depth, or do we instead produce one single layer of content but presented with “infoboxes” or “appendices” so that the informed visitors can dig deeper?
-
scope: hand in hand with the issue of depth, there is the issue of scope: should the tutorials be so encompassing as to include even the most exotic parts of the language? should it go beyond what’s covered in, say, the excellent “Haskell Programming from First Principles”, and talk about Arrows and the whole train of language pragmas? should it step beyond the language proper and talk about debugging/profiling/compiling/building?
-
collaboration with original authors: do we ask authors to somehow rewrite bits of their contents directly for us or do we rather do the work ourselves, assuming they assent to us re-using their work, and perhaps ask them to review the end result later?
My personal takes:
- (1) could be more language centric and (2) more tools-centric, in the sense that (2) could also show people how to start a project with cabal/stack and show them the basics of project management. But I reckon it’s perfectly possible to talk about tools in (1) instead, and juse (2) more like interactive examples of the material covered in (1);
- I think 1 layer is much easier to maintain
- I think it’s good to minimize efforts and instead let authors “work for us” in the sense that we have the final cut (because we have the editor’s point of view and can work on integration) while also crediting them thoroughly so that there is a visible record for them to reference in their resume or something.
Visual overhaul of the docs
I think it’s way too soon to talk about visuals. This contrasts with the issue of
Structural overhaul of the docs
https://www.haskell.org/documentation/ is too flat (lacks structure) and too long. If this page is to serve as an entry point to most of the Haskell documentation available on the web, the best approach is probably to put oneself in the shoes of the newcomer, and structure everything around concrete, practical issues, something like:
-
Fast lane for the impatient: a simple walkthrough from installing the tools to running a very simple program (unavoidable calculator or hangman programs come to mind here) in 10 minutes max.
-
Learning the Haskell Language
- core concepts and comparison with other languages
- language-centric tutorials
- basic language extensions
- case study: let’s look at concrete samples of code in actual projects and see what we can learn from them
-
Doing Real Things with Haskell
- best use cases
- tools-centric tutorials covering project management basic routines such as:
- dependencies managemenent
- debugging
- building with options
- profiling & optimizing
- tips and best practices for production
-
Peeking between the curtains
- GHC and advanced langage extensions
- Core tutorials
On the issue of restructuring this web page, the points we need to settle on are as follows:
- are we OK with marking a clear distinction between the language per se and the use of it, including toolchains?
- are we OK with giving more of a spotlight to use and toolchains?
- are we OK with doing efforts for giving more exposure to practical / usable-in-production Haskell than is usually done in online material?
- are we OK with doing integration work, editorial work, and sometimes creating our own contents to fill certain holes?
Maintainance and sustainability
Who maintains the doc? Who’s in charge? To be sure if no one is in charge all efforts will be partially wasted, because the whole thing will eventually rot (best practices change; assumptions about what people know beforehand need updating; GHC changes; tools change). If one wants this volunteering effort to blossom into something sustaible, this question should not be sidestepped.
On this issue the important questions to discuss are:
- are we OK with a maintainer-centric contribution model, whereby some volunteers act as mediators to accept/review/organize reviews on/ submitted contents?
- are we OK with implementing this model, should we choose it, using a git-style stack?
