[RFC] Documentation overhaul on haskell.org

Hi @ketzacoatl, I received your request and responded to it 22 hours ago to your email address: Your desired username is already taken (It was registered in 2016). Is it possible that you already have an account? If not, please send a different username choice.

We generally respond to requests within 24 hours, often much sooner. In your case, the request went into my spam folder so it took me 18 hours to respond. Perhaps my response went into your spam folder?

I would be happy to open up self-registration, but it has quickly led to a lot of spam in the wiki. If there is a better solution available we’d be happy to try it.

1 Like

Hello @hgolden, You would be correct! Thank you for reaching out to sync up! :slight_smile:

If there is a better solution available we’d be happy to try it.

IDK if it is available in the wiki software, but enabling auth through google/github/gitlab/etc seems to be a reasonable solution to this problem.

1 Like

@ketzacoatl, I just looked at MediaWiki’s manual on authorization and authentication. It looks like your suggestion can be implemented using recent extensions. We need to give this a try. It would allow users who have authenticated with common services (e.g., Google) to become authorized just by using their credentials from the other services. This will take some work and testing, but it looks very promising. I hope other interested readers will offer their opinions on this approach.

2 Likes

I’m absolutely in favor of this idea.

This sounds excellent.

If there’s anything I can do to help, let me know. I’ve spent the last five years teaching programming to folks with no previous coding experience and also learnt Haskell myself (with no CS experience) fairly recently. I was thinking of writing a book… but we probably don’t need another one.

1 Like

Ideally, the auth plugins would support Github/GitLab/Google, but even if it’s limited to Google, it seems worthwhile to try it out, or at least offer as an alternative option.

I don’t want to tame a nice flame, but I am a bit sceptical of any non-distributed solution, as it exposes the docs to unnecessary risks (backup errors, dependence upon “root” credentials, doc writer gone mad and sabotaging things, etc.). It’s also impossible to work seriously on the docs offline. Why not simply use a static web site generator building sources files from a public repo and deploying the result on the Foundation’s infra, with mirrors where appropriate? It’s seems it’s the way most important Free, Libre and Open Source projects work nowadays. And using a Haskell software would be the cherry on the top. :ok_hand:

9 Likes

This seems nice. Reduce the number of moving parts, rely on GitHub/Netlify for the infrastructure concerns. Also to make it even more accessible for people to propose updates for Haskell’s documentation, while still retaining the control on which changes are to be applied (main contributors). Dogfooding an existing Haskell library also means we could spot problematic parts, or not so well documented features.

4 Likes

Yup.

A battle-proven (as in: “what several Linux distributions do”) recipe goes like this:

  1. Open one or several GitHub repos, seeded with a static web site generator.
  2. Work there, enjoying the well-known workflow and the visibility that the platform offers you. Build the docs whenever you feel like. Serve using GitPages or anywhere else (HFoundation for example).
  3. When you feel like you’ve grown enough that GitHub is more of a constraint than anything else, for instance when you need to coordinate several repositories, or when you want to really be in control of your files, you set up a Pagure instance on, say, the HFoundation’s infrastructure, with its own internal repositories, leaving behind the GiHub repos as mere mirrors for safety and visibility.

After (3), there is one remote hub for hosting and working on the docs, but the docs is still decentralized in the sense that anyone can replicate the whole at home and work on it offline.

6 Likes

I was thinking of writing a book… but we probably don’t need another one.

Is there any rationale why you think we don’t need another book?

I personally think that we need much more books. It’s maybe 30 of them in the Haskell world, a half of them is not good / complete enough or is just obsolete. Even golang, which is a language two orders of magnitude simpler than Haskell, has more than 60 books. Not saying how many hundreds of books have other mainstream languages.

5 Likes

Rather than dropping the Haskell wiki, please consider adding content to it. 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.

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.

If you don’t have a wiki username, please ask for one. We’ll set it up for you promptly (This is a spam reduction measure that we hope to replace soon).

If you prefer some flavor of markup other than MediaWiki markup, please run your content through Pandoc and paste the result into the wiki.

2 Likes

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 :slight_smile:

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).

It’s ok to let things change for the better.

5 Likes

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.

2 Likes

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.

7 Likes

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.

5 Likes

By the way, regarding “I’m still not sure where to submit a proposal to base”:

https://wiki.haskell.org/Core_Libraries_Committee and
https://wiki.haskell.org/Library_submissions

should direct you.

Note that the former is linked from the “community” section of the haskell.org homepage, as the first link under “committees”.

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.

1 Like

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?

CSS anyone?

Nope, CSS nobody

2 Likes

@sclv,

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.

4 Likes