How, precisely, can we improve?

[Christopher Allen]

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
<chak at justtesting.org> wrote:
> Michael’s arguments are compelling.
>
> Manuel
>
> Simon Peyton Jones via ghc-devs <ghc-devs at 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.zimm at gmail.com]
> Sent: 27 September 2016 15:54
> To: Simon Peyton Jones <simonpj at microsoft.com>
> Cc: Sven Panne <svenpanne at gmail.com>; ghc-devs <ghc-devs at 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 at 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-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://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 at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>
>
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>
>
>
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>



-- 
Chris Allen
Currently working on http://haskellbook.com