[RFC] Documentation overhaul on haskell.org

#62

docs on haskell.org 1 compete with those on wiki.haskell.org

this is very true.

Regardless of what people think the wiki is or should be (“not a tutorial” etc.), the fact is that it appears high on search engines, I’m guessing because people nowadays associate “wiki” with “wikipedia”, i.e. an authoritative reference, whereas in typical Haskell fashion we adhere to the original meaning of things (in this case, a collectively editable document).

It is therefore of paramount importance to clarify that the wiki is not a reference on the language. Do we have any SEO experts in the house?

1 Like
#63

I’ve opened a thread on the Wiki specifically, let’s continue there all related discussion

1 Like
#64

Sure, looks good to me!

#65

2 posts were merged into an existing topic: [RFC] Evolution of wiki.haskell.org

#66

With this very welcome clarification of yours that the wiki is not (normative ‘is not’ I understand) a reference on the language, and many concrete proposals on the table, could we look into an in-person meeting to lay out everyone’s assumptions, expectations and desires in view of putting together a proper docs team for the overhaul?

How do all the participants to this topic interested in contributing to the overhaul feel about this?

#67

To clarify a bit further something that may be confusing, really only two pieces of “truly official” documentation exist. That is the ghc users guide, and of course, the haskell report. Everything else is a resource created and maintained by some individuals but with no “blessed” status other than that the documentation page points to it as useful.

So there are three avenues to proceed on 1) reorganizing / curating the links that exist, adding new ones as well, etc. 2) encouraging individual efforts to fill out certain areas where it is felt that something is missing. 3) production of new “hf blessed” documentation in certain desired areas. The first and second appear somewhat coupled to me, the third a larger and more distinct area of endeavour. I would encourage people to organize into perhaps two groups based on which they were interested in. The initial proposal leaned more towards 1/2, but ensuing discussion seemed to be more interested in 3, from what I’ve read.

1 Like
#68

I think you’re barely scratching the surface, mate. My understanding is that, as evidenced here, many people would like to see better docs for onboarding Haskell and learning reputable and good libraries. That’s the context from which @ocramz spawned this post. If we are faithful to this context, we have to expect much more work and coordination/collaboration than is implied by “reorganizing links” or “encouraging individual efforts”. We are talking seeding a process that will bring us closer to the Rust landing page (as hinted at by @ocramz in OP), with its mouthful of on-site contents to guide and help newcomers. :slight_smile:

#69

Right, well that’s area 3. Which I’m noting that people are also interested in, just a different area of endeavor, not least because it is significantly more ambitious :slight_smile:

Note that rust in part has been able to do things like this because it has had more than just volunteer efforts put into such documentation – i.e. it has paid people to produce it.

4 Likes
#70

f-a:

the unfortunate fact is that for satisfactory documentation you need editors: lots of them, responsive, available for long stretches of time. […] Editing is far from a hot job too […]

Exactly.

sclv:

What is needed is for somebody to step up and write really amazing, brilliant [Haskell] docs.

[…] it [the Rust community] has paid people to produce it.

Bingo: people who can write really amazing, brilliant documentation are probably using that talent to draw an income.

Writing documentation is one of those onerous and thankless chores of software development, up there with maintaining the project’s build system: when was the last time you sat down and read the manual for one of your appliances, let alone some new suite of programs?

No one cares about documentation until they need to use it - at that point, the last thing anyone’s interested in is improving it: they just want their problem solved right now, or they’ll just look for an alternative.

At the very least, if we want someone to invest the considerable time and effort into providing high-quality documentation, we need them to use a format which can stand the test of time - as close to being “future-proof” as we can have it, instead of having to keelhaul docs from one “latest-and-greatest” format to the next (as some of the comments here about wikis eludes to).

Regarding the transfer of docs to the Haskell website: how does one get an account there? I just tried:

“haskell.org” new account

in my preferred search engine; most results on the first page are about Hackage…

3 Likes
#71

In the footer of the site haskell.org there is the text:

Got changes to contribute to the site? Fork or comment on GitHub

1 Like
#72

I am inquiring about an account on haskell.org, not Github.

#73

haskell.org doesn’t have accounts as far as I’m aware. If you want to transfer documentation to haskell.org then you should do it via GitHub.

1 Like
#74

This is odd - why is the content on GitHub when there’s gitlab.haskell.org? Surely it can be extended beyond just serving the needs of GHC…

#75

Gitlab historically was managed by the ghc team for ghc only. When the website was created, I don’t think it even existed (ghc still used phab – and it may have even been prior to that).

One could certainly migrate the repo to gitlab, but as is, many committees/working-groups/processes have been leaning towards github for all sorts of things still. (i.e. the ghc proposals process). I’m not sure what would be gained from a move at this point in time…

Also on the broader question, please note that there is no established place in haskell.org to currently transfer general documentation to. The main website is relatively small, consisting of about five main pages and a few subpages. So if people want to move increasing amounts of documentation there, I think some structure would need to be put in place to organize it.

Also, I don’t think a static hakyll site is necessarily the best way to organize large mounts of documentation that people are working on – surely better tools than this must exist? If there’s some specific tool or way of organizing things people want, perhaps it could be setup at subdomain such as docs.haskell.org so people can browse, organize, and contribute independent of the main site? I note this is how rust seems to work – there’s a doc.rust-lang.org subdomain that mainly hosts auto-built sphinx documentation.

#76

That’s a great point, someone wrote a git-book clone in rust, it’s called mdBook. AFAICT, that’s what the rust-lang project uses:

Having docs.haskell.org as a static site rendered from a tool like mdbook is a nice way to manage the site with git and markdown. I have used mdbook, my experience with it was positive.

3 Likes
#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