[RFC] Documentation overhaul on haskell.org

#77

For software, documentation exists to facilitate its use - if the software doesn’t exist (or never will), there’s no need for documentation:

sclv:

[…] perhaps it could be setup at a subdomain such as docs.haskell.org […]

code.haskell.org makes more sense - then the docs can be (rightly) paired with the corresponding software project. It could even be made a requirement for adding new projects - no useful docs, no new code! (Obviously, if an existing site e.g. hackage.haskell.org could be configured to operate in this manner, all the better…)

Then www.haskell.org only has to host one form of documentation - how to use Haskell. This could also be made conditional - each new proposal for a language extension must be accompanied by useful documentation, otherwise it will simply be ignored.

So, in this bright, shiny alternate reality:

(about code.haskell.org)

  • you want to add your project ? Make sure its documentation is fit for purpose!

  • you want your project to stay? Make sure its documentation stays fit for purpose!

  • you found a problem with some piece of documentation for a project on code.haskell.org? Send that project some (polite!) feedback.

  • you are interested in improving some piece of documentation for a project on code.haskell.org? Join that project!

(about www.haskell.org)

  • you want to add your proposal to extend the language? Make sure it’s adequately-documented, and make some time to answer any questions regarding your proposal.

  • you want your proposal to stay? Make sure it stays adequately-documented, and answer those questions.

  • you have a question about some language proposal? Ask it’s authors.

  • you want to improve a proposal’s documentation or answer a pertinent question? Join its authors.

…now back to this reality: documentation doesn’t appear at the flick of a wand - someone has to make the effort to write it. If it’s the project’s coders that are doing it, that’s less time for them to add that cool new feature or hunt down those annoying bugs - do try to remember that when the projects you like are running late with their next versions: coding (or documenting) will probably help more than complaining.

#78

In regard to the recent posts above – most notably from @atravers – urging us to be aware of the time and sustained effort to accomplish a genuine overhaul I am once again asking to the participants to this topic whether they’d be interested in scheduling a meeting of some sort, so as to lay all the cards on the table, sync up on desires and capabilities, and look into funding the overhaul so as to honour our ambition.

(Also this presupposes that funding is an actionable option; can you confirm or infirm that’s the case @f-a @ocramz?)

#79

I am not in any way linked to the Haskell Foundation.

#80

I am interested in participating

#81

Does one need to be a member of the Haskell Foundation to attend such a meeting? (Currently my only interest in this involves substantial editing by myself of several pages on the Haskell wiki - it would be unfortunate if some of that work couldn’t be salvaged somehow…)

1 Like
#82

I am not a member of the Haskell foundation nor have I any position in any official Haskell institutions, yet I’d be really glad to have such a meeting.

#83

A clarification on my part: code.haskell.org has previously been used: my cursory check missed that detail - I thought it was an “blank” URL…

As for a meeting: it would be better if we can figure out the general concept first, then have one with someone from the HF to discuss the details with, to see what’s possible (particularly in regards to funding…and domains >_< )

#84

I was going to try to (somehow) summarise the suggestions so far into something that could be used as the basis for an initial stratagey, but my 'net connection is flaking out (and Discourse along with it )-:

I missed the link to it on my initial skim though this comment-a-thon: there’s already work underway to update the website, and it seems the Document Task Force is already doing some work on the wiki.

I think I have a simpler two-part plan:

  • Improve what we’ve got now - we can talk to the DTF as to what to work on, or (as I have been doing out of blissful ignorance :slight_smile: ) find some online Haskell content that interests (or annoys) you and dive in…

  • Work on Pandoc (if I remember the name correctly) to support more formats - that way, if we absolutely have to switch to some other format, it can be done more-or-less automatically.

Signing off - over and out.

#85

I have nothing against this approach, and Pandoc is a good tool.

By the way I am not sure it’s a good idea to keep procrastinating with regard to a very needed meeting, however. I’v been working with several Linux distributions in volunteers’ project and in my experience trust, motivation and coordination need a genuine meeting to kick off. Exchanging text messages just doesn’t cut it.

#86

It seems like there is an appetite for having a meeting for interested parties to make contact with each other and discuss collaborative efforts to improve Haskell documentation. That’s great!

I would strongly encourage those interested parties to take the initiative and just go for it! Anyone is welcome to contribute to the work of the Haskell Foundation. It doesn’t require any sort of approval from the HF board.

That being said, the HF Documentation Task Force is led by board member Hecate Choutri (https://discourse.haskell.org/u/Kleidukos) and I am a board member on that task force. I would be happy to take the lead facilitating such a meeting if it would be helpful to get the ball rolling, and I imagine Hecate would feel the same.

Let’s try and keep up this valuable enthusiasm.

2 Likes
#87

Let me know if there’s still enthusiasm for this.

#88

A ton of enthusiasm, but I am not sure we’re on the same page as far as a meeting is concerned. I don’t really know what more I should do to facilitate this.

#89

Time to bring in the professionals!

The HF can hire a team of three experienced “web-publishers” to go through the content on both www.haskell.org and wiki.haskell.org with a view to building something like the proverbial “Rust book” - for anything they consider irrelevant to the task (particularly on the wiki), the authors of the original page can be contacted to move their content elsewhere, otherwise it can be archived e.g. as a .zip or compressed .tar file, for future cyber-historians to download from e.g. archive.haskell.org as needed.

Regarding the wiki, if several of the comments here are any measure:

…then the site (and “centrally-located” wikis more generally) have mostly served its purpose, and can now be retired:

  • Again for those future cyber-historians, a "full page archive" (including all page histories) in a suitable compressed format;

  • For people who actually want to keep the wiki going on an alternate site, a “meta-data archive” from the current wiki server (which would also include all the data in the "full-page archive");

  • For everyone else, a “final-version archive”, just containing the most recent snapshots of all pages or their final versions, if the wiki is going offline permanently.

Of course, these are just suggestions, with the final decisions being left to the publishing team - if we don’t like what they choose, we as a community should have done what’s required for ourselves. Clearly that didn’t happen.

(In case you’re wondering: yes - I’m the author of several recently-added pages on the wiki, so I too will most likely be affected by this course of action. But having stale content from the wiki constantly appearing in search results will only have more people wondering about the future of Haskell…)

2 Likes
[RFC] Evolution of wiki.haskell.org
#90

The point about Rust Book is confusing. Are they gonna turn the wiki into a book somehow? The book is a different format entirely.
And who would “own” the content after that? For how long?

2 Likes
#91

I opened this related issue on the haskell-infra github page recently: Updating the Documentation page · Issue #189 · haskell-infra/www.haskell.org · GitHub . I really like the idea of the Haskell Foundation spending budget on improving the newcomer experience (via well coordinated and clear guidance on resources), because it seems like a very cost effective way of getting more people into the community. And there’s a virtuous cycle where good resources get attention, which gives them motivation to be maintained.

3 Likes
#92

No. I’m just suggesting that the content from both sites may be useful in writing something like a “Haskell book” - exactly how much of that content they would actually use, and what for, is their decision. For all I know, they may have a better idea than a “Haskell book” : they’re the professionals, not me.

And who would “own” the content after that? For how long?

I suggested they would be working on behalf of the HF, so it would presumably belong to the HF since they would be funding the endeavour. Will the HF be disappearing any time soon?

#93

I hope not :sweat_smile: But the HF wouldn’t be able to manage the product continuously either and it will go stale exactly as wiki did.

#94

Why is that finite? Why could it not be maintained by the community, or even annually, on an ongoing-basis by the HF itself?

#95

That leaves the HF with a decision: do they keep the publishing team on an ongoing basis?

Back when Haskell (the language and libraries) was “small”, bringing in such a team on a periodic basis e.g. on a short-term contract (less than one year) would have been a reasonable choice. But now Haskell has grown much larger, so keeping the publishing team around seems the better option to keep all the documentation relevant.

How would the HF do that (e.g. permanent staff, long-term contractors, etc)? I don’t know - ask them instead. But who knows: the HF may now have their own ideas, and mine has been made redundant…

#96

For the same reason the wiki isn’t actively maintained :woman_shrugging: