<div dir="ltr"><div>I think this is relevant to the dicussion: <a href="http://www.yesodweb.com/blog/2015/08/thoughts-on-documentation">http://www.yesodweb.com/blog/2015/08/thoughts-on-documentation</a><br><br></div>Alan<br></div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Sep 27, 2016 at 4:22 PM, Simon Peyton Jones via ghc-devs <span dir="ltr"><<a href="mailto:ghc-devs@haskell.org" target="_blank">ghc-devs@haskell.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div link="blue" vlink="purple" lang="EN-GB">
<div><span class="">
<p class="MsoNormal" style="margin-left:36.0pt">We currently have *3* wikis:<u></u><u></u></p>
<p class="MsoNormal" style="margin-left:36.0pt"><u></u> <u></u></p>
<p class="MsoNormal" style="margin-left:36.0pt"> <a href="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" target="_blank">
https://wiki.haskell.org/<wbr>Haskell</a><u></u><u></u></p>
<p class="MsoNormal" style="margin-left:36.0pt"> <a href="https://ghc.haskell.org/trac/ghc" target="_blank">
https://ghc.haskell.org/trac/<wbr>ghc</a><u></u><u></u></p>
<p class="MsoNormal" style="margin-left:36.0pt"> <a href="https://phabricator.haskell.org/w/" target="_blank">
https://phabricator.haskell.<wbr>org/w/</a><u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
</span><p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif">I didn’t even know about the third of these, but the first two have clearly differentiated goals:<u></u><u></u></span></p>
<p><u></u><span style="font-size:11.0pt;font-family:Symbol"><span>·<span style="font:7.0pt "Times New Roman"">
</span></span></span><u></u><a href="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" target="_blank">https://wiki.haskell.org/<wbr>Haskell</a>
is about user-facing, and often user-generated, documentation. Guidance about improving performance, programming idioms, tutorials etc.<span style="font-size:11.0pt;font-family:"Calibri",sans-serif"><u></u><u></u></span></p>
<p><u></u><span style="font-family:Symbol"><span>·<span style="font:7.0pt "Times New Roman"">
</span></span></span><u></u><a href="https://ghc.haskell.org/trac/ghc" target="_blank">https://ghc.haskell.org/trac/<wbr>ghc</a> is about GHC’s implementation, oriented to people who want to understand how GHC works, and how to modify it.<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">I think this separation is actually quite helpful.<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">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.<u></u><u></u></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif">Simon<u></u><u></u></span></p>
<p class="MsoNormal"><a name="m_-6044542434727342922__MailEndCompose"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif"><u></u> <u></u></span></a></p>
<div style="border:none;border-left:solid blue 1.5pt;padding:0cm 0cm 0cm 4.0pt">
<div>
<div style="border:none;border-top:solid #e1e1e1 1.0pt;padding:3.0pt 0cm 0cm 0cm">
<p class="MsoNormal"><b><span style="font-size:11.0pt;font-family:"Calibri",sans-serif" lang="EN-US">From:</span></b><span style="font-size:11.0pt;font-family:"Calibri",sans-serif" lang="EN-US"> ghc-devs [mailto:<a href="mailto:ghc-devs-bounces@haskell.org" target="_blank">ghc-devs-bounces@<wbr>haskell.org</a>]
<b>On Behalf Of </b>Sven Panne<br>
<b>Sent:</b> 27 September 2016 08:46<br>
<b>To:</b> ghc-devs <<a href="mailto:ghc-devs@haskell.org" target="_blank">ghc-devs@haskell.org</a>><br>
<b>Subject:</b> Re: How, precisely, can we improve?<u></u><u></u></span></p>
</div>
</div><div><div class="h5">
<p class="MsoNormal"><u></u> <u></u></p>
<div>
<div>
<p class="MsoNormal">Just a remark from my side: The documentation/tooling landscape is a bit more fragmented than it needs to be IMHO. More concretely:<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal"> * We currently have *3* wikis:<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"> <a href="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" target="_blank">
https://wiki.haskell.org/<wbr>Haskell</a><u></u><u></u></p>
<p class="MsoNormal"> <a href="https://ghc.haskell.org/trac/ghc" target="_blank">https://ghc.haskell.org/trac/<wbr>ghc</a><u></u><u></u></p>
<p class="MsoNormal"> <a href="https://phabricator.haskell.org/w/" target="_blank">https://phabricator.haskell.<wbr>org/w/</a><u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal"> 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
<a href="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" target="_blank">
haskell.org</a> in an easily reachable place.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal"> * 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.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal"> * <a href="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" target="_blank">https://haskell-lang.org/</a>
has great stuff on it, but its relationship to <a href="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" target="_blank">
haskell.org</a> is unclear to me. Their "documentation" sub-pages look extremely similar, but
<a href="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" target="_blank">
haskell-lang.org</a> has various (great!) tutorials and a nice overview of common libraries on it. From an external POV it seems to me that
<a href="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" target="_blank">
haskell-lang.org</a> should be seamlessly integrated into <a href="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" target="_blank">
haskell.org</a>, i.e. merged into it. Having an endless sea of links on <a href="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" target="_blank">
haskell.org</a> is not the same as having content nicely integrated into it, sorted by topic, etc.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">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.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">Furthermore, I'm quite aware of the technical/social difficulties of my proposals, but that shouldn't let us stop trying to improve...<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">Cheers,<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"> S.<u></u><u></u></p>
</div>
</div>
</div></div></div>
</div>
</div>
<br>______________________________<wbr>_________________<br>
ghc-devs mailing list<br>
<a href="mailto:ghc-devs@haskell.org">ghc-devs@haskell.org</a><br>
<a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs" rel="noreferrer" target="_blank">http://mail.haskell.org/cgi-<wbr>bin/mailman/listinfo/ghc-devs</a><br>
<br></blockquote></div><br></div>