[RFC] Documentation overhaul on haskell.org

#42

It doesn’t belong to the site. It isn’t part of the main site, its just also in a subdirectory hosted on haskell.org, much like e.g. https://www.haskell.org/haskell-symposium/

Modernizing the design without modernizing the content doesn’t make much sense, but its also a famous and classic work that documents the language as of when it was written. So I’d like to see it preserved in its “classic” form somewhere. I know that navigating between that and “help make sure people find current and useful material” isn’t always easy. I just want to make sure we bear these competing imperatives in mind.

#43

I think this is an area important enough for the future adoption of Haskell, that it warrants its own working group and agenda.

Perhaps the same process that is being followed for creating a technical agenda could be used for creating a documentation one. The group working on this problem would ideally have the motivation for discussing and implementing with the help of the community any changes that they deem suitable. Being transparent, like with the technical agenda, will be crucial for its success.

#44

The Haskell Foundation has a documentation task force. It is led by Théophile “Hécate” Choutri. See Haskell Foundation Update 2021-03-19 for some more details. The Wiki already falls under its purview.

4 Likes
#45

Hécate is doing a great job with overhauling documentation in general, but I think the Wiki/Haskell.org content is going to need its own spin-off at some point to address the points that both @ketzacoatl and @sclv raise.

Looking at the exchange above, it seems there’s a disconnect between what is expected of contributors, and plans + attitudes for the future of important documentation. I know that in the past, the Haskell.org committee has been open and welcoming to contributions from the community with respect to the site docs, but it’s only been relatively recent that they’ve considered archiving the Wiki and providing curated excerpts from it as part of the officially linked docs on the site. I think now is a good time to start talking about organizing the work to get that all done!

So what I propose here is that the HF and Haskell.org committee team up to help organize volunteers for making the Haskell.org content more modern, along with getting the requisite changes to the Wiki done. We’ll need to storyboard what the new pages and their content might look like, as well as find a subset of the wiki to officially bless and link to after archiving. I think this would be a great showcase for our ability to organize groups of folks to do things.

5 Likes
#46

I think we should iron out a possible disagreement. As I’ve tried to emphasis here and there, I think in agreement with this reply, wikis are an a “poisoned gift” to offer to the community:

  • unnecessary centralization of the docs (when it’s easy to go for decentralization with git-style repositories), which means exposure to credentials abuses and data loss
  • difficult to work on the docs offline
  • messy, gerry-mandered, easily corruptible updates (when there is a clean and tested workflow via submit / push requests)
  • “no one is in charge” or “hit-and-run” mentality, which sucks immensely if we want to apply decent QA standards
  • and more or less as consequence of the above: horrible reliability, because the user will never be able to know for sure if what they’re reading is both (a) officially recommended and (b) up-to-date.

Notice that none of these issues exist on decentralized, git-style SVC models. I surmise this is why no decently organized body, especially in the open source community, is extensively relying on wikis for cutting-edge and reliable technical information in 2021.

Thus I think it would be very naive or arrogant – not targetting anyone, just sayin’, as a general attitude toward the notion of progress – to not take a page from their book: let’s acknowldge that a high-quality Haskell documentation has nothing to gain from wikis, and sideline this platform once and for all. (For overhauling the documentation, I should add; wikis have a perfectly good use case, i.e. as a public and collective workspace for community activities, events, and storage room).

Personnally, I don’t think I would be able to build up a sufficient amount of motivation to commit hours of work on anything that looks like a wiki. Just can’t, for the love of all.

9 Likes
#47

Arch Linux folks have maintained their docs — high quality, reliable, up to date, multi-language — using a Wiki for 17 years and running.

As an infrequent contributor (who is agnostic about tooling) to a handful of communities, the unfortunate fact is that for satisfactory documentation you need editors: lots of them, responsive (community contribution is discouraged the more friction there is), available for long stretches of time.

Editing is far from a hot job too: «I spent some of my time curating Template Haskell docs» looks less blazing than «I have written an Xyz abstraction library» on your résumé. Alas, looking at our community, one beautiful project like HCAR has been discontinued due to lack of manpower.

I am happy to see threads like these, it means the topic is important for the community. Good luck to @Kleidukos in their efforts to channel this energy into top notch docs!

4 Likes
#48

I certainly don’t disagree with this, and I don’t think anyone does that I’ve seen. I’m not advocating anyone use the wiki above anything else. I’m saying, as I have been, that there is much amazing content in that wiki, some dating back well before github existed (and to a period when wikis were the broad standard), and that content, even the stuff that is out of date, should be preserved and accessible. If nobody disagrees with that either, then I don’t know if there’s actual disagreement or just a lot of static.

I will also again say that where the content is hosted is rather orthogonal to whether or not it even exists, and also to how people coordinate pointing to it.

Speaking from long experience, it is far too easy to say “this is the technical reason that X has not occurred” and you change the technical thing, and it doesn’t change the real issue, which is that people just aren’t doing it (which is a question of social coordination).

2 Likes
#49

I notice that the analogy with Arch wiki does not address the concerns I’ve raised. Also I worry that the argument from analogy with the Arch wiki breaks at multiple levels, but the main one becomes clear when you look at

image
image1203×1190 213 KB

source: ArchWiki:Statistics - ArchWiki

What these numbers suggest is that Arch Wiki behaves exactly like a git-style repo: 80%+ of the contributions are made by 20%- of the users. To this you must add the overhead of managing users through 90s-style read/write roles. In other words, Arch Wiki is trying to be a git-style monorepo.

My suggestion is that we don’t ape git-style repos, and instead be honest and acknoweldge that a git-style repo is what we need.

But perhaps there is also a misunderstanding about the end goal, about what it means to “overhaul haskell.org”'s documentation. For me that means starting to get serious, and aim for something like this. In steps:

  1. setup a maintainer-centric contribution model
  2. collecting material from this gloriously good example, and various other places such as:
  1. Turn the result of (2) into something that will probably look like something between a supercharged version of Learn You a Haskell and The Python Tutorial — Python 3.10.0 documentation.

If there still disagreement on whether we should use git-style repos, or if we simply want to get started with this thing, how about simply meeting in person to discuss things in a more convenient way on an audio/video platform? I’ve noticed that meeting helps immensely when you start things because it tends to minimizes disagreement and it feeds on everyone’s positive energy!

5 Likes
#50

Literally nothing is stopping you from gathering a team and following those steps at this very instant, and as far as I know literally nobody is saying “you should use the haskell wiki as the place to put what you generate.” I’m not sure how this thread got derailed to the point where the two issues were at all related. If you manage to get something like that produced, I’m sure it will be a wonderful resource, and I think there’s a docs team connected to the HF that would love to coordinate on it (if you’re not already synced with them).

#51

I don’t understand your comment. You sure do see that it would be doing the same work twice over to keep working on the wiki while having a separate team, with no coordination with the wiki team, do their own in-house thing, right?

I mean, both options are ways of doing the exact same thing – provide approachable yet rigourous documentation and tutorials on Haskell catered for new & slightly advanced users to be eventually hosted on haskell.org. Or did I miss somethin?

#52

You seem to misunderstand the content on the wiki. The purpose of the wiki is not and has never been “approachable yet rigourous documentation and tutorials on Haskell catered for new & slightly advanced users”. This may be the confusion! Some pages may have attempted to fulfill that purpose, but there are many pages, with many purposes!

The wiki has been a catch-all over the years to hold all sorts of material – some people have documented their own libraries on it, some people have documented the state of a particular ecosystem, or some special corner of fusion, or category theory, or an approach to a specific sort of problem, or code-puzzles or exercises, or solutions to such. Other pages on the wiki are articles, like submissions to the Monad Reader publication. Other pages are just tutorials on how to get a particular gui lib or the like even building.

Other pages on the wiki just document decisions in Haskell history, choices that were made over time in terms of language design, or e.g. past logos which have been associated with the Haskell language.

Even the stuff on the wiki that is “approachable yet rigorous documentation and tutorials” does not preclude other things existing. You might as well say that we should take the Haskell books out of print or shut down Haskell blogs that try to do this, since it “duplicates work”.

There will be a plethora of documentation, and there is. Nothing on the Haskell wiki (with a few exceptions of protected pages) even resembles official. It’s a community wiki that happens to be hosted on the haskell.org domain. There is no split work between keeping what the community has already produced over years around, and also producing a new focused, official thing.

If this new effort attracts the attention of people that might otherwise be wiki gardeners, great, more power to it. But it is odd to pose that something that has served a different purpose, for years, stands in the way of a new effort not yet underway.

I urge and encourage you to work with HF to get the project underway that you want to get underway. Nothing is stopping you. If at some point it seems that there’s confusion on where to point, or what is more “official” then we can resolve it at that point, based on what content this new project has produced.

4 Likes
#53

Well, this one is easy:

  • @ocramz does not make a single mention of the wikis in the OP
  • @ocramz 's first occurrence of the word “wiki” is in a comment where he writes that the Haskell wiki needs some serious love […] but that this is not exactly high on the todo list
  • @graninas calls for a “massive redesign” of the haskell.org documentation platforms
  • @ketzacoatl calls for “dropping the wiki completely”

and numerous other people in this thread have expressed concerns that the wikis might not play a significant role in improving haskell.org’s documentation, at least, not as a final product offered to the community (although pulling good docs out of the wikis and offering them a better shelter is surely in order).

So yeah, I think it’s oblivious of the obvious to not want to confront this issue head on.

#54

Right the entire discussion up until the introduction of the wiki red herring was on other topics, because the wiki is not relevant. It serves a different purpose. I also agree that wikis are not necessarily the best place to serve a final product offered to the community as official documentation. So I think that whatever disagreement you are seeing doesn’t exist. I’m just explaining the wiki historically has served a different purpose.

Suppose I told someone they should get rid of their cat, because it is not a good chef. You might rightfully respond that a cat is a pet, not a chef. That’s how I feel at the moment.

1 Like
#55

@sclv This post ([RFC] Documentation overhaul on haskell.org) last paragraph suggests that the notion that the wiki deserves more volunteering efforts is still alive, and it is this notion which I would like to put to bed (it instead deserves recycling, or so I’ve tried to argue).

So no, this discussion is not diverging into two unrelated issues. There is no divergence because the two issues are intimately connected: whether the wikis should be improved or recycled is a fundamental issue that anyone serious about moving this topic forward has interest in seeing settled upon.

#56

I feel we should get the conversation back on the original topic : documentation .

Let’s forget the wiki for a moment since it’s clearly many different things to different people.

Can we all agree on an agenda of important things to do regarding documentation on the homepage, give this agenda to the HF Board for approval and/or split it into actionable items that a group of volunteers can make happen ?

To follow due process, we should also articulate a concrete proposal and submit it to the Committee for publication and visibility in the broader community : https://github.com/haskell-org/committee

As I initially wrote: I think the major areas of improvement are:

Ping @Kleidukos @emilypi

4 Likes
#57

I find the wiki-discussion here a bit of a distraction from the original topic and also my recommendations for that (my suggestion to fold the wiki into the haskell.org docs is critical to a doc overhaul, and is not destroying/deleting that content). However, there is one really important point about the wiki which makes it relevant and necessary to keep in context with respect to a “documentation overhaul on haskell.org”, and that is how docs on haskell.org compete with those on wiki.haskell.org. This is a significant problem, and the way to fix it is to move that content to an authoritative copy on haskell.org, with old wiki pages updated to reference that authoritative page on haskell.org. There is no need to maintain wiki.haskell.org, we should not be paying for that admin time or infrastructure costs. Also, there is some duplication that needs to be found and addressed.

4 Likes
#58

@emilypi, it isn’t clear to me what you mean by “archiving the Wiki.” Could you please clarify this? This needn’t be an either/or choice.

Wikis are not meant to host official content. I’m not suggesting that the Haskell wiki should be used for this purpose.

However, I still believe that the Haskell wiki can be a useful place to collect “organic” content that users generate and allow other users to edit (I categorically reject @Nycticorax’s statement that “wikis are a ‘poisoned gift’ to offer the community.”) Instead, community members should be encouraged to link wiki pages on particular topics to their blog posts and Github/Gitlab code. These uses are unofficial, but can be helpful in organizing community content.

I have the sense that the Haskell wiki isn’t expensive to maintain (Is this correct?), so I hope it will be kept alive and improved (for example, by linking topics to official content stored elsewhere and removing or annotating old content that no longer applies).

1 Like
#59

Original poster clarified what the scope of this discussion is. If anyone wants to debate tangent matters — what to do with HaskellWiki, etc. —, please consider opening a new thread.

3 Likes
#60

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
#61

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

1 Like