I appreciate your efforts to maintain and support the wiki as public infrastructure. I don’t mean to belittle that work or it’s impact. I know what that work is like
At the same time, to be practical and prudent, we need to be honest with ourselves.
Wikis had their time and place, but that time has moved on. A resource like wiki.haskell.org can be safely replaced with better means of accomplishing the goals the wiki intended to fulfill. The wiki may have served it’s purpose well in the past, but it can no longer compete with alternatives. For example, GitLab and GitHub both offer better options for signup, posting content to the web, moderation and reviewing changes as a group, maintaining transparency, etc, etc. The same can be said for static site generators, which even haskell.org is maintained with. There is no benefit provided by the wiki, it is simply added weight we don’t need to carry.
Rather than dropping the Haskell wiki, please consider adding content to it.
I have, and I don’t think that’s the place for me (or anyone else) to add content. I believe the haskell.org website and this discourse instance (and people’s own personal blogs) are much better places for the content that is up on the wiki.
This is a good place to refine content that can be curated later into a complete and authoritative guide. For example, the GHC gitlab wiki contains some general usage information that would be more available to users in the wiki.
I disagree, and I believe it would make a lot more sense to
a) use git and the git workflow,
b) use markdown (or whatever the guide’s markup will be).
Please consider adding links to your blog posts, github projects, etc. on the appropriate wiki pages (or add new pages as needed). The wiki is a good place to save these connections where they can be discovered by interested readers.
I believe this discourse instance is a better place for those types of posts (as well as other resources such as the haskell.org website the haskell weekly newsletters, reddit, etc).
I like that on a wiki you can have one page, e.g. Web/Frameworks, with several different packages/approaches listed. On discourse you often just have a single package/approach per post, which can make it difficult to discover alternatives (and often posts here are about new developments and not about stable mainstream solutions).
I also think that such information should be on a publicly editable website, so not on haskell.org. The main alternative then would be something like a GitLab Pages backed static site. I don’t know the differences between the Wiki and GitLab workflows very well, but sounds like it could be an improvement.haskell.org is publicly editable, so that would be a good place to put this information.
I like that on a wiki you can have one page, e.g. Web/Frameworks, with several different packages/approaches listed.
That isn’t out of place on haskell.org, in fact it would make a lot of sense to include in the authoritative tutorial. It would also stay more up-to-date on haskell.org, as opposed to the wiki.
I also think that such information should be on a publicly editable website, so not on haskell.org. The main alternative then would be something like a GitLab Pages backed static site. I don’t know the differences between the Wiki and GitLab workflows very well, but sounds like it could be an improvement.
Haskell.org is a publicly editable website, with a lower barrier to entry. It’s a static/generated site, with a collaborative and transparent process for applying edits.
The wiki is no long a “better” option for what haskell.org uses it for. The content on the wiki should be migrated and the site retired.
I have made my stance clear on the wiki several times, and I’ll do so again. That wiki contains precious history which cannot be deleted. It can be archived, and older pages marked clearly as such. It is already often superseded in many areas, and that’s fine. However, there is much of importance and interest on the wiki, some of only archival interest I’ll grant, and some not. Please stop suggesting it be deleted.
I think it makes perfect sense to host lots of stuff elsewhere, and point people to newer stuff, but don’t suggest destroying older material.
Regarding accounts – we have tried and tried again to implement automated systems to prevent spam, and time and time again spammers have foiled them. One could try again, I suppose. However, when there are automated account systems then that does not mean less work for admins, it means more, because they need to spend more time hunting down the spammers that invariably slip through the cracks. There are not enough curators on the wiki or other systems to do this effectively. I’m sorry this means a slightly higher barrier to entry. It also means that the systems do not degrade into vandalized spam-farms.
I would note that both these questions are really unrelated to what it means to improve the documentation section. What is needed is for somebody to step up and write really amazing, brilliant docs. At which point, then the section can point to them.
I agree on not deleting the wiki content as a whole, but a good trimming is in order. Certain pages are little more than an uncut conversation between anonymous participants, in addition to being obsolete.
What is needed is for somebody to step up and write really amazing, brilliant docs. At which point, then the section can point to them.
and who will judge whether submissions clear this bar? I think 2021 haskell.org should incorporate the best content out there (after a voting process!), make it the official learning material, rather than being a link dump.
Even the hallowed “Gentle introduction to Haskell Version 98” by Hudak et al (https://www.haskell.org/tutorial/ ) doesn’t even look like it belongs to the site. CSS anyone?
Let me first say that I appreciate your efforts to support and help the Haskell Community. As a relative newcomer, it does not take long perusing mailing lists, github, etc, etc to run into your contributions. I can see the passion you have, and I find that inspiring.
That said, I am troubled by your response, as it seems I am not being understood all that well. I have also re-read your message several times, and still find it difficult to not read your message as an attempt to silence me from being heard. It seems you would like to stop my ideas from being recognized for what they are. Maybe you don’t realize your impact, but why would you do that?
The last sentence in my previous post was:
The content on the wiki should be migrated and the site retired.
How are you interpreting my statements as advocating for deleting/destroying that wiki content?
How and why are you conflating the two, and then repeating it so many times in your reply?
You have my apologies if I haven’t been clear enough on explicitly stating that content should be reviewed and migrated.
It can be archived, and older pages marked clearly as such.
Yes, exactly, and we can archive content on haskell.org.
I advocate for moving archived and authoritative pages to haskell.org where they can be more properly recognized and maintained as such. I do not advocate for losing the history.
It’s a static site and super easy to do with git, no history will be lost.
It is also important to do this because the authoritative documentation on haskell.org must not compete with the wiki on that content. The content from the wiki (along with content from other sources), should be folded together into the documentation on haskell.org. The wiki on haskell.org comes across as authoritative when it is not, and when it also conflicts with haskell.org.
If we want to preserve the history, we should migrate the content to git because an admin could delete the server by mistake.
It should be a community-driven effort, and admins such as yourself should find ways to help support the community in movements we are looking to make, not block and impede meaningful change.
However, there is much of importance and interest on the wiki, some of only archival interest I’ll grant, and some not.
Great! The important content should be identified and moved to haskell.org. That’s the easy part!
If you would kindly help identify that content, I would also be happy to help follow thru with moving the content to haskell.org. It’ll happen thru pull requests, so everyone can see and participate in that workflow.
This statement realllllly increases the difficulty/challenge for a positive response to your post. I wish other leaders in the community would step up and talk to you about this when you do it.
As a newb, stepping out into a large forum, stepping up to make my meek voice be heard for a moment, you in your position could stop for a moment and listen carefully. You could be welcoming, and you could even strive to understand what I’m advocating for or why I would think it worthwhile to stand up and risk embarrassment or looking like a fool?
It is inappropriate for an admin such as yourself to use your position as leverage as you have here.
Please be more aware of your position and how you communicate with the community.
In case I need to explain myself further: For someone in a position of power to say, “I have made my stance clear”, there is more that such a statement communicates, especially when received by someone of lower standing. For example, I also hear:
how dare you challenge me
you do as I say
what you have said has no standing and makes no sense
And in the future, when I go to post, I’ll have to put aside my concern for how you may respond.
I would guess you don’t intend to act or come across poorly, and I share this trusting you in your position as willing to receive such feedback.
Regarding accounts – we have tried and tried again to implement automated systems to prevent spam, and time and time again spammers have foiled them. One could try again, I suppose. However, when there are automated account systems then that does not mean less work for admins, it means more, because they need to spend more time hunting down the spammers that invariably slip through the cracks. There are not enough curators on the wiki or other systems to do this effectively. I’m sorry this means a slightly higher barrier to entry. It also means that the systems do not degrade into vandalized spam-farms.
I agree, admin time should not be wasted with those things. This is part of why I believe the content should be migrated to haskell.org where we as a community can more easily manage and evolve that content as an authoritative source. The community can carry the majority of that work, admins don’t need to be burdened.
I would note that both these questions are really unrelated to what it means to improve the documentation section.
As someone who has struggled with haskell and the community’s dysfunction (this type of thing you are doing now is a significant contributor to the dysfunction we experience), I have to disagree.
As an experienced haskeller who has been in an adminstrative role for N years, I assume you are too close to see the impact and how this is all related. I don’t expect you to just get it, but I do expect you to put in more effort to understand why people want changes that you call into question.
What is needed is for somebody to step up and write really amazing, brilliant docs. At which point, then the section can point to them.
No, many people have done that, several times over, but they’ve done it elsewhere, and in pieces. They did that after attempting to work with you and your committees, or after witnessing how you interacted with someone before them, and they went and did their own thing b/c they believed trying to get your support was a waste of their time.
Yes, I agree, the content needs review and a lot of love. I believe it would be best to review the content as part of migrating it over. I started this effort with the wiki page on the haskell.org committee, because there were TWO pages on public haskell.org pages claiming to be the authoritative page and both of which were incomplete. We’re still working to get the wiki page updated, but there are so many hurdles and only so much time to voluneer for jumping over stuff like this.
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.
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.
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.
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.
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.
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!
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).
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
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:
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!
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).
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?
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.
