[RFC] Documentation overhaul on haskell.org

#40

CSS anyone?

Nope, CSS nobody

2 Likes
#41

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