I tend to agree, particularly as it would permit automated processing and conversion of the documentation much more readily than a website really ever has.
I don't think I've ever used a public wiki that enforced broken link checking, whereas that's a sundry CI check for static markdown documentation. Markdown files can become anything somebody wants, including a web server hosting it as HTML documentation that looks however they want. This approach doesn't prevent separating docs for the community vs. implementors either. Just a subdirectory if you wanted. On Wed, Sep 28, 2016 at 9:30 PM, Manuel M T Chakravarty <c...@justtesting.org> wrote: > Michael’s arguments are compelling. > > Manuel > > Simon Peyton Jones via ghc-devs <ghc-devs@haskell.org>: > > 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:alan.z...@gmail.com] > Sent: 27 September 2016 15:54 > To: Simon Peyton Jones <simo...@microsoft.com> > Cc: Sven Panne <svenpa...@gmail.com>; ghc-devs <ghc-devs@haskell.org> > 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 > > Alan > > On Tue, Sep 27, 2016 at 4:22 PM, Simon Peyton Jones via ghc-devs > <ghc-devs@haskell.org> wrote: > > We currently have *3* wikis: > > https://wiki.haskell.org/Haskell > 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 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-boun...@haskell.org] On Behalf Of Sven Panne > Sent: 27 September 2016 08:46 > To: ghc-devs <ghc-devs@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://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 > 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/ has great stuff on it, but its relationship > to haskell.org is unclear to me. Their "documentation" sub-pages look > extremely similar, but haskell-lang.org 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 should be seamlessly integrated into haskell.org, i.e. > merged into it. Having an endless sea of links on haskell.org 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@haskell.org > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs > > > _______________________________________________ > ghc-devs mailing list > ghc-devs@haskell.org > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs > > > > _______________________________________________ > ghc-devs mailing list > ghc-devs@haskell.org > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs > -- Chris Allen Currently working on http://haskellbook.com _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs