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 < [email protected]> 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:[email protected]] *On Behalf Of *Sven > Panne > *Sent:* 27 September 2016 08:46 > *To:* ghc-devs <[email protected]> > *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 > [email protected] > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs > >
_______________________________________________ ghc-devs mailing list [email protected] http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
