Here's a pre-proposal (which could be formalized into a proper proposal) to address the wiki discussion:
- Configure the wiki to display the date of last edit prominently. - If the date of last edit is sufficiently long ago (1 year?) loudly warn the reader that the content may be out-of-date. And that's it! I think that solves the problem. The reason this solves the problem is that the ghc-proposals process is already en route to providing the git-backed files that have been floated as the alternative to a wiki. Thus, language features, etc., will be memorialized through the ghc-proposals process. As I understand it, that process already requires the proposal to be updated to a description of the feature as the feature is implemented and refined. We will be left with a nice git repo of feature descriptions. The wiki can remain as a place for less permanent discussions (such as pre-proposals) or pages that use the nice dynamic features of Trac. Is this proposal possible to implement? Does it solve the wiki problem sufficiently? Sometimes, solutions are easy. :) Richard > On Sep 28, 2016, at 10:30 PM, Manuel M T Chakravarty <[email protected]> > wrote: > > Michael’s arguments are compelling. > > Manuel > >> Simon Peyton Jones via ghc-devs <[email protected] >> <mailto:[email protected]>>: >> >> Interesting article. Michael suggests using markdown in repo-controlled >> files rather than a wiki. I can see the force of that. Maybe we should >> consider it. >> >> Simon >> <> >> From: Alan & Kim Zimmerman [mailto:[email protected] >> <mailto:[email protected]>] >> Sent: 27 September 2016 15:54 >> To: Simon Peyton Jones <[email protected] <mailto:[email protected]>> >> Cc: Sven Panne <[email protected] <mailto:[email protected]>>; ghc-devs >> <[email protected] <mailto:[email protected]>> >> Subject: Re: How, precisely, can we improve? >> >> I think this is relevant to the dicussion: >> http://www.yesodweb.com/blog/2015/08/thoughts-on-documentation >> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.yesodweb.com%2Fblog%2F2015%2F08%2Fthoughts-on-documentation&data=01%7C01%7Csimonpj%40microsoft.com%7C7ff5e6e47ba5499a774308d3e6e631c2%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=uXvFVL2YlOPej5%2Brxms7oUL91OD%2FpqDD9VLaOYtL%2FjQ%3D&reserved=0> >> Alan >> >> On Tue, Sep 27, 2016 at 4:22 PM, Simon Peyton Jones via ghc-devs >> <[email protected] <mailto:[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://ghc.haskell.org/trac/ghc> >> https://phabricator.haskell.org/w/ >> <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 <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] >> <mailto:[email protected]>] On Behalf Of Sven Panne >> Sent: 27 September 2016 08:46 >> To: ghc-devs <[email protected] <mailto:[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://ghc.haskell.org/trac/ghc> >> https://phabricator.haskell.org/w/ >> <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] <mailto:[email protected]> >> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs >> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fmail.haskell.org%2Fcgi-bin%2Fmailman%2Flistinfo%2Fghc-devs&data=01%7C01%7Csimonpj%40microsoft.com%7C7ff5e6e47ba5499a774308d3e6e631c2%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=6YMRMy74y45Vudt%2F2GvIEOj%2BautOYf7H4Uw%2BaDUMYbM%3D&reserved=0> >> >> _______________________________________________ >> ghc-devs mailing list >> [email protected] <mailto:[email protected]> >> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs >> <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
_______________________________________________ ghc-devs mailing list [email protected] http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
