As we were discussing on [RFC] Documentation overhaul on haskell.org , the Haskell wiki plays an ambiguous role as pertains to language documentation.
It is on one hand highly visible (usually ranks high in search engine results) but unfortunately it’s not an authoritative reference by any measure.
It would be nice to figure out a path out of this situation, that doesn’t burn bridges with the tradition but lets Haskell documentation catch up with the current state of the art.
I agree with everything said here. For me it’s a matter of curation: the more rigorous and up-to-date bits of the wiki about the Haskell language and the Haskell production toolchain should be extruded from the wiki and eventually make into a maintainer-centric, officially acknoweldged and sustainable, platform. Then we can proceed recursively, from most to least up-to-date and rigourous, judging on a case-by-case basis what is worth improving in view of putting into the official docs about the Haskell language and production tooolchain docs, and what isn’t.
In other words, I am suggesting that we take out articles in the “Learn Haskell” and “Use Haskell” to a more sustainable platform until only the articles under the circled in red categories remain:
And that is fine, because wikis are excellent tools for community things.
Honestly the whole frontpage should be redone to make it point to lots of the more interesting resources and content. A little history is in order – for years, the wiki was the haskell.org homepage, and about five (?) years ago a real homepage was produced and the wiki moved off to a subdomain. So the wiki frontpage was produced for a wiki that served a dual purpose as a homepage and also a repo of community curated content. Most of the links on that page (both circled and not) do not point to wiki content, but offsite content. A few links point to onsite content which in turn is an index of offsite content. Most of what the wiki itself hosts that is cool and interesting is not immediately reachable from the frontpage through a few links at all, and most of what is reachable on the frontpage are links the haskell.org website point to.
Turning it into a frontpage that explains the purpose of the wiki and highlights some of the unique content in the wiki would probably clear up a lot of confusion. Along with that, a template for tagging particularly old content with potential links to newer resources could be used on some pages, and between the two that might alleviate a number of concerns.
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.
I mean turning it into a read-only archive, as mentioned by @sclv. The idea being that there is valuable knowledge that needs to be preserved, but so many articles are so out of date that any effort to get the wiki back up to date would be at this point nearly impossible. And those articles vastly outnumber the gems. So making the wiki read-only, and curating the immutably useful articles would be i our best interest.
Wikis are not meant to host official content. I’m not suggesting that the Haskell wiki should be used for this purpose.
Unfortunately, this happened, and that’s part of the problem. Sometime in the past, it was used for Hackage announcements, package tutorials, etc etc, and it spiraled into something less useful than we want it to be.
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.”)
FWIW, i disagree with @Nycticorax’s comment as well - I’m much more sympathetic than that, considering I got my start in the Typeclassopedia and other great articles!
I think this will expose my bias: I don’t think wikis serve a purpose beyond aggregating immutable data (this is rarely the case for software), but we’re past that point. Even implementation-specific GHC pages, like the performance-oriented wiki articles are completely out of date and actually liable to get people into trouble, or turned around in the wrong direction.
There are better ways of aggregating and indexing blog posts/announcements/etc. For example, we have Planet Haskell which does this.
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).
It’s inexpensive, sure, but for the Haskell wiki to serve a purpose, we must keep it small, immutable, and community-managed. At the moment, we are none of these things. I know you and Gershom have been great at keeping the lights on, but maintenance is not the goal here: progressive maintenance is the goal. Wikis must be kept up to date, and have janitorial processes as part of what we call maintenance.
Something to bear in mind in this discussion of the wiki, perhaps the single most important aspect, is that search engines often send confused new users to outdated and confusing wiki pages rather than newer and clearer sources of information.
emilypi:
I don’t think wikis serve a purpose beyond aggregating immutable data […]
A curious comment considering the manifestly-mutable nature of wikis - wouldn’t a more static format then be more appropriate?
tomjaguarpaw:
[…] search engines often send confused new users to outdated and confusing wiki pages […]
Such is the nature of wikis and similar online forums - they’re a semi-organised collection of individual web-pages edited by a variety of people with varying levels of knowledge and experience. Some are well-written or edited; as for the rest…not so much. Of course, this is irrelevant to the average search engine: if the search term matches them, such pages will be in the results no matter how outdated and confusing they are.
(Just imagine using a wiki to learn how to drive - aren’t you glad you had access to a much-more organised source of information?)
As for making the current wiki read-only, that happened to the previous wiki and its content - from the few pages I’ve seen and transferred over recently, their content being:
little more than an uncut conversation between anonymous participants, in addition to being obsolete
…isn’t exactly rare (quote from here).
The results of a second freeze (on the current wiki) probably wouldn’t be much different. As for the more general problem of content: well, there’s a reason why academic texts are usually written by people with a degree or three to spare…
(…as for the suggestion the wiki not be used for documentation: it only solves that problem - the difficulties of stale or garbled content aren’t limited to documentation.)
Have new plans emerged since March? Should we spend time on curating Wiki pages? If so, what should we focus on? I would love to help improve the status quo which is unacceptable.
My opinion, after a similar “pause of discussion”:
Of wow, is this really happening, or is this irony?
…maybe it’s still in that pile.
I’m not sure Haskell is a coherent/single thing in the way other languages try to be – such that it’s possible to condense the myriad wikis into ‘a’ book. Even the 2010 Language definition (which is now next to useless) was way behind what compilers actually supported at the time.
I had the advantage of picking up Haskell soon after 2010, when there was still a relatively small footprint of extensions; and it was clear what was the nub. Even so, I occasionally come across ‘new’ features that date back to 2010. I’ve been able to add knowledge piecemeal so I can navigate my way round the design space. I fear if I was tackling Haskell from fresh today, it would be just bewildering.
Still there’s no clear choice between FunDeps vs Type Families – as much as anything it’s a question of personal preference; but you have to choose one to use Multi-param type classes; and that choice leads on to other tendencies.
Some code is GADT-intensive. Some prefers to use Pattern Syns to achieve much the same effect. That a library uses one rather than the other may reflect only that GADTs were available much earlier. (The relatively late arrival of PattSyns might explain why some longer-standing libraries don’t use them despite that giving a more friendly ‘programmer interface’.)
I guess a wiki could be constructed as concentric circles(?):
-XGHC2021 ‘blessed’ extensionsI’ve written User Guide/wiki material over the years. Most of it has bitrotted by now. Some of it, looking back, I should have said more – but where do you stop writing as a language reference vs programming tips?
And then there’s the gazillions of Warning and Sanity-check options …
There’s plenty of papers with older example programs/styles of writing programs that are useful learning models, even though we wouldn’t do it that way these days. Somewhere(?) we need to preserve enough of the wiki that folks can learn from them.
I would recommend starting by marking out of date or incorrect information as such, or even deleting it, if that is warranted. I think the wiki is too far gone for “curation” to be a worthwhile endeavour. The best we can do is risk management.
But those aren’t necessarily out of date or incorrect? I strongly oppose deleting information just for the sake of it.
I agree with Tom that triaging may be a good first step. One challenge is how to do it technically. I think, one technical step that would make it easier to work on the wiki would be to export it to some modern form, e.g. a git repository. Maybe even creating a mirror out of the repository. Having an issue tracker and a PR process may unblock an army of volunteers.
I’m judging by the success of learnyouahaskell.github.io — a recent community fork of the renowned textbook, which already have seen a good number of external contributions improving on decade-long problems that everyone knew about but no one knew what to do about. The process is the message.
I think this is a good idea @artem. This addresses the justified conserncs of @sclv, and also allows for a more streamlined maintenance and editing process. I think we should also use a different markup language (this is not a hard constraint).
Pandoc does support the wikimedia format. I am just not sure about automatic conversion, we would need to check every single page… Are there other ways?
…well, judging by the “success” of:
just taking a Git-dump of old content doesn’t always work, either. One immediate difference between LYAH and the wiki is that LYAH only had one author, so presumably only that person had to be asked.
While the more-permissive licencing of the [current version of] the wiki means everyone who’s contributed content doesn’t need to be asked…shouldn’t there already be a Git-dump somewhere as a result of said licencing, considering the burgeoning “Git-house” industry?
The Haskell Wiki license allows for dumps and subsequent changes (and relicencing if required): HaskellWiki:Copyrights - HaskellWiki.
I am not sure about the license of contributions before 2006-1-14. What happens if a page has contributions from before 2006, do we have to ask the contributors in this case? Many will not beavailable anymore.
A more pragmatic side: How would we call this dump? It is not anymore a Wiki in the sense that it won’t be a MediaWiki. Calling it “book” would be a bit to much of the “Let’s copy what Rust is doing” mentality.
Notes on how to create dumps:
A simple suggestion:
instruct the crawler programs for the various search engines to ignore everything below wiki.haskell.org;
(optional) place the Search HaskellWiki feature in a more prominent location in the content of wiki.haskell.org.
Yes, it also affects more regularly-maintained content - that’s why it’s a suggestion. But it would at least stop stale content from appearing in search results, and people can use the wiki’s own search facilities as needed.
There’s a problem with the suggestions to completely delete HaskellWiki or to hide from search engines, and I don’t see it mentioned yet.
There’s a number of old but still useful packages on Hackage whose only documentation is on that Wiki. Some examples are MemoTree and multiplate.
The two packages are also prime examples of well-designed, general-purpose Haskell libraries that are basically timeless: they can remain useful forever with no maintenance. In other words, they are exactly the kind of code we don’t want to break - including their documentation.
Anybody who advocates for deprecating the existing HaskellWiki pages IMO needs to make a list of links from Hackage to these pages, and to present a plan for their maintenance.