How, precisely, can we improve?

[Michael Sloan]

On Tue, Sep 27, 2016 at 9:18 AM, Eric Seidel <eric at seidel.io> wrote:
> On Tue, Sep 27, 2016, at 09:06, Richard Eisenberg wrote:
>> Yes, I agree with Michael’s observations in the blog post. However, one
>> thing that’s easier about a wiki is that the editing process is much more
>> lightweight than making a PR.
>>
>> But GitHub has a wonderful feature (that I have rarely used) that
>> mitigates this problem. Viewing a file in GitHub offers a little pencil
>> icon in the top-right. It allows you to make arbitrary changes in the
>> file and then automates the construction of a PR. The owner of the file
>> can then accept the PR very, very easily. If the editor has commit
>> rights, you can make your edits into a commit right away. No need to
>> fork, pull and push.
>
> Indeed, GitHub also supports git-backed wikis, so you can have nicely
> rendered and inter-linked pages *and* have the option for web-based or
> git-based editing. Though, based on my limited experience with GitHub
> wikis, I wonder if they would scale to the size of GHC's wiki..

I agree, I don't think GitHub wikis are sufficient for GHC.  We've
tried using GitHub wikis, and found that they were clunkier than just
having wiki / docs in your repo.  GHC would probably want to have a
separate docs repo, as otherwise the commit history will get filled
with commits related to proposals, etc.

It may be worth considering a similar approach with the GHC
documentation.  We've had great success in stack with using
https://readthedocs.org/ .  The way this works is that you have a
branch that readthedocs points at ("stable"), which provides the
current version to display.  I realize that ghc would want to have
multiple versions of the docs up, but I'm sure that's feasible.

Github itself has pretty nice markdown rendering, and the ability to
edit directly.  Note that there is no GitHub lock-in here - it is just
a collection of markdown files, organized however you like them.

The risk with such a migration is that the old wiki(s?) don't get
fully migrated and shut down.  If that happens, then information will
be even more spread out and hard to find.  Perhaps we can use pandoc
to automatically migrate much of the wiki content to markdown?  It
probably will not be a lossfree conversion.

> There's also a tool called gitit (https://github.com/jgm/gitit) that
> seems to offer the same set of features, but apparently with a more
> traditional (and I assume customizable) layout.
>
> I think having the option for simple, immediate edits or peer-reviewed
> edits (the peer-review is much more important to me than having an
> explicitly file-based system) would be a big win. Perhaps there's even a
> trac module that implements something like this? Then we could decouple
> it from the question/task of migrating the existing content elsewhere.
>
> Eric
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs