[RFC] Documentation overhaul on haskell.org

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:

  1. 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.
  2. 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?
3 Likes

I would like to add http://learn.hfm.io/ to the list of learning materials that we can draw inspiration from.

1 Like

docs on haskell.org 1 compete with those on wiki.haskell.org

this is very true.

Regardless of what people think the wiki is or should be (“not a tutorial” etc.), the fact is that it appears high on search engines, I’m guessing because people nowadays associate “wiki” with “wikipedia”, i.e. an authoritative reference, whereas in typical Haskell fashion we adhere to the original meaning of things (in this case, a collectively editable document).

It is therefore of paramount importance to clarify that the wiki is not a reference on the language. Do we have any SEO experts in the house?

1 Like

I’ve opened a thread on the Wiki specifically, let’s continue there all related discussion

1 Like

Sure, looks good to me!

2 posts were merged into an existing topic: [RFC] Evolution of wiki.haskell.org

With this very welcome clarification of yours that the wiki is not (normative ‘is not’ I understand) a reference on the language, and many concrete proposals on the table, could we look into an in-person meeting to lay out everyone’s assumptions, expectations and desires in view of putting together a proper docs team for the overhaul?

How do all the participants to this topic interested in contributing to the overhaul feel about this?

To clarify a bit further something that may be confusing, really only two pieces of “truly official” documentation exist. That is the ghc users guide, and of course, the haskell report. Everything else is a resource created and maintained by some individuals but with no “blessed” status other than that the documentation page points to it as useful.

So there are three avenues to proceed on 1) reorganizing / curating the links that exist, adding new ones as well, etc. 2) encouraging individual efforts to fill out certain areas where it is felt that something is missing. 3) production of new “hf blessed” documentation in certain desired areas. The first and second appear somewhat coupled to me, the third a larger and more distinct area of endeavour. I would encourage people to organize into perhaps two groups based on which they were interested in. The initial proposal leaned more towards 1/2, but ensuing discussion seemed to be more interested in 3, from what I’ve read.

1 Like

I think you’re barely scratching the surface, mate. My understanding is that, as evidenced here, many people would like to see better docs for onboarding Haskell and learning reputable and good libraries. That’s the context from which @ocramz spawned this post. If we are faithful to this context, we have to expect much more work and coordination/collaboration than is implied by “reorganizing links” or “encouraging individual efforts”. We are talking seeding a process that will bring us closer to the Rust landing page (as hinted at by @ocramz in OP), with its mouthful of on-site contents to guide and help newcomers. :slight_smile:

Right, well that’s area 3. Which I’m noting that people are also interested in, just a different area of endeavor, not least because it is significantly more ambitious :slight_smile:

Note that rust in part has been able to do things like this because it has had more than just volunteer efforts put into such documentation – i.e. it has paid people to produce it.

4 Likes

f-a:

the unfortunate fact is that for satisfactory documentation you need editors: lots of them, responsive, available for long stretches of time. […] Editing is far from a hot job too […]

Exactly.

sclv:

What is needed is for somebody to step up and write really amazing, brilliant [Haskell] docs.

[…] it [the Rust community] has paid people to produce it.

Bingo: people who can write really amazing, brilliant documentation are probably using that talent to draw an income.

Writing documentation is one of those onerous and thankless chores of software development, up there with maintaining the project’s build system: when was the last time you sat down and read the manual for one of your appliances, let alone some new suite of programs?

No one cares about documentation until they need to use it - at that point, the last thing anyone’s interested in is improving it: they just want their problem solved right now, or they’ll just look for an alternative.

At the very least, if we want someone to invest the considerable time and effort into providing high-quality documentation, we need them to use a format which can stand the test of time - as close to being “future-proof” as we can have it, instead of having to keelhaul docs from one “latest-and-greatest” format to the next (as some of the comments here about wikis eludes to).

Regarding the transfer of docs to the Haskell website: how does one get an account there? I just tried:

haskell.org” new account

in my preferred search engine; most results on the first page are about Hackage…

3 Likes

In the footer of the site haskell.org there is the text:

Got changes to contribute to the site? Fork or comment on GitHub

1 Like

I am inquiring about an account on haskell.org, not Github.

haskell.org doesn’t have accounts as far as I’m aware. If you want to transfer documentation to haskell.org then you should do it via GitHub.

1 Like

This is odd - why is the content on GitHub when there’s gitlab.haskell.org? Surely it can be extended beyond just serving the needs of GHC…

Gitlab historically was managed by the ghc team for ghc only. When the website was created, I don’t think it even existed (ghc still used phab – and it may have even been prior to that).

One could certainly migrate the repo to gitlab, but as is, many committees/working-groups/processes have been leaning towards github for all sorts of things still. (i.e. the ghc proposals process). I’m not sure what would be gained from a move at this point in time…

Also on the broader question, please note that there is no established place in haskell.org to currently transfer general documentation to. The main website is relatively small, consisting of about five main pages and a few subpages. So if people want to move increasing amounts of documentation there, I think some structure would need to be put in place to organize it.

Also, I don’t think a static hakyll site is necessarily the best way to organize large mounts of documentation that people are working on – surely better tools than this must exist? If there’s some specific tool or way of organizing things people want, perhaps it could be setup at subdomain such as docs.haskell.org so people can browse, organize, and contribute independent of the main site? I note this is how rust seems to work – there’s a doc.rust-lang.org subdomain that mainly hosts auto-built sphinx documentation.

That’s a great point, someone wrote a git-book clone in rust, it’s called mdBook. AFAICT, that’s what the rust-lang project uses:

Having docs.haskell.org as a static site rendered from a tool like mdbook is a nice way to manage the site with git and markdown. I have used mdbook, my experience with it was positive.

3 Likes

For software, documentation exists to facilitate its use - if the software doesn’t exist (or never will), there’s no need for documentation:

sclv:

[…] perhaps it could be setup at a subdomain such as docs.haskell.org […]

code.haskell.org makes more sense - then the docs can be (rightly) paired with the corresponding software project. It could even be made a requirement for adding new projects - no useful docs, no new code! (Obviously, if an existing site e.g. hackage.haskell.org could be configured to operate in this manner, all the better…)

Then www.haskell.org only has to host one form of documentation - how to use Haskell. This could also be made conditional - each new proposal for a language extension must be accompanied by useful documentation, otherwise it will simply be ignored.

So, in this bright, shiny alternate reality:

(about code.haskell.org)

  • you want to add your project ? Make sure its documentation is fit for purpose!

  • you want your project to stay? Make sure its documentation stays fit for purpose!

  • you found a problem with some piece of documentation for a project on code.haskell.org? Send that project some (polite!) feedback.

  • you are interested in improving some piece of documentation for a project on code.haskell.org? Join that project!

(about www.haskell.org)

  • you want to add your proposal to extend the language? Make sure it’s adequately-documented, and make some time to answer any questions regarding your proposal.

  • you want your proposal to stay? Make sure it stays adequately-documented, and answer those questions.

  • you have a question about some language proposal? Ask it’s authors.

  • you want to improve a proposal’s documentation or answer a pertinent question? Join its authors.

…now back to this reality: documentation doesn’t appear at the flick of a wand - someone has to make the effort to write it. If it’s the project’s coders that are doing it, that’s less time for them to add that cool new feature or hunt down those annoying bugs - do try to remember that when the projects you like are running late with their next versions: coding (or documenting) will probably help more than complaining.

In regard to the recent posts above – most notably from @atravers – urging us to be aware of the time and sustained effort to accomplish a genuine overhaul I am once again asking to the participants to this topic whether they’d be interested in scheduling a meeting of some sort, so as to lay all the cards on the table, sync up on desires and capabilities, and look into funding the overhaul so as to honour our ambition.

(Also this presupposes that funding is an actionable option; can you confirm or infirm that’s the case @f-a @ocramz?)

I am not in any way linked to the Haskell Foundation.