How, precisely, can we improve?

Tue Sep 27 14:54:11 UTC 2016

I think this is relevant to the dicussion:
http://www.yesodweb.com/blog/2015/08/thoughts-on-documentation

Alan

On Tue, Sep 27, 2016 at 4:22 PM, Simon Peyton Jones via ghc-devs <
ghc-devs at haskell.org> wrote:

> We currently have *3* wikis:
>
>
>
>         https://wiki.haskell.org/Haskell
> <https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell&data=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=fxYacdt9XklXJaGetQABBI%2BG3IgnlJmB2r1EL54I1HU%3D&reserved=0>
>
>         https://ghc.haskell.org/trac/ghc
>
>         https://phabricator.haskell.org/w/
>
>
>
> I didn’t even know about  the third of these, but the first two have
> clearly differentiated goals:
>
> ·        https://wiki.haskell.org/Haskell
> <https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell&data=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=fxYacdt9XklXJaGetQABBI%2BG3IgnlJmB2r1EL54I1HU%3D&reserved=0>
> is about user-facing, and often user-generated, documentation.  Guidance
> about improving performance, programming idioms, tutorials etc.
>
> ·        https://ghc.haskell.org/trac/ghc is about GHC’s implementation,
> oriented to people who want to understand how GHC works, and how to modify
> it.
>
>
>
> I think this separation is actually quite helpful.
>
>
>
> I agree with what you and others say about the difficulty of keeping wikis
> organised. But that’s not primarily a technology issue: there is a
> genuinely difficult challenge here.  How do you build and maintain
> up-to-date, navigable, well-organised information about a large, complex,
> and rapidly changing artefact like GHC?  A wiki is one approach that has
> the merit that anyone can improve it; control is not centralised.  But I’d
> love there to be other, better solutions.
>
>
>
> Simon
>
>
>
> *From:* ghc-devs [mailto:ghc-devs-bounces at haskell.org] *On Behalf Of *Sven
> Panne
> *Sent:* 27 September 2016 08:46
> *To:* ghc-devs <ghc-devs at haskell.org>
> *Subject:* Re: How, precisely, can we improve?
>
>
>
> Just a remark from my side: The documentation/tooling landscape is a bit
> more fragmented than it needs to be IMHO. More concretely:
>
>
>
>    * We currently have *3* wikis:
>
>
>
>         https://wiki.haskell.org/Haskell
> <https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell&data=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=fxYacdt9XklXJaGetQABBI%2BG3IgnlJmB2r1EL54I1HU%3D&reserved=0>
>
>         https://ghc.haskell.org/trac/ghc
>
>         https://phabricator.haskell.org/w/
>
>
>
>
>
>      It's clear to me that they have different emphases and different
> origins, but in the end this results in valuable information being
> scattered around. Wikis in general are already quite hard to navigate (due
> to their inherent chaotic "structure"), so having 3 of them makes things
> even worse. It would be great to have *the* single Haskell Wiki directly on
> haskell.org
> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fhaskell.org&data=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=%2F8JlCXTwn%2FB8EyrW4BkY0QTS57X%2BFvs4BSXijqCbiNA%3D&reserved=0>
> in an easily reachable place.
>
>
>
>    * To be an active Haskell community member, you need quite a few
> different logins: Some for the Wikis mentioned above, one for Hackage,
> another one for Phabricator, perhaps an SSH key here and there...
> Phabricator is a notable exception: It accepts your GitHub/Google+/...
> logins. It would be great if the other parts of the Haskell ecosystem
> accepted those kinds of logins, too.
>
>
>
>    * https://haskell-lang.org/
> <https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fhaskell-lang.org%2F&data=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=9ndNQVeDQy7lPb4qmn13k%2BAtztK8F9Hq%2B2jeXKm9YFU%3D&reserved=0>
> has great stuff on it, but its relationship to haskell.org
> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fhaskell.org&data=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=%2F8JlCXTwn%2FB8EyrW4BkY0QTS57X%2BFvs4BSXijqCbiNA%3D&reserved=0>
> is unclear to me. Their "documentation" sub-pages look extremely similar,
> but haskell-lang.org
> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fhaskell-lang.org&data=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=G9e%2BVDuPTtZHZl%2BGd2fFShUznQjDa158JENjoMiD0VY%3D&reserved=0>
> has various (great!) tutorials and a nice overview of common libraries on
> it. From an external POV it seems to me that haskell-lang.org
> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fhaskell-lang.org&data=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=G9e%2BVDuPTtZHZl%2BGd2fFShUznQjDa158JENjoMiD0VY%3D&reserved=0>
> should be seamlessly integrated into haskell.org
> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fhaskell.org&data=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=%2F8JlCXTwn%2FB8EyrW4BkY0QTS57X%2BFvs4BSXijqCbiNA%3D&reserved=0>,
> i.e. merged into it. Having an endless sea of links on haskell.org
> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fhaskell.org&data=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=%2F8JlCXTwn%2FB8EyrW4BkY0QTS57X%2BFvs4BSXijqCbiNA%3D&reserved=0>
> is not the same as having content nicely integrated into it, sorted by
> topic, etc.
>
>
>
> All those points are not show-stoppers for people trying to be more active
> in the Haskell community, but nevertheless they make things harder than
> they need to be, so I fear we lose people quite early. To draw an analogy:
> As probably everybody who actively monitors their web shop/customer site
> knows, even seemlingy small things moves customers totally away from your
> site. One unclear payment form? The vast majority of your potential
> customers aborts the purchase immediately and forever. One confusing
> interstitial web page? Say goodbye to lots of people. One hard-to-find
> button/link? A forced login/new account? => Commercial disaster, etc. etc.
>
>
>
> Furthermore, I'm quite aware of the technical/social difficulties of my
> proposals, but that shouldn't let us stop trying to improve...
>
>
>
> Cheers,
>
>    S.
>
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20160927/d989f95e/attachment-0001.html>