How, precisely, can we improve?

[Richard Eisenberg]

I'm quite leery of using a new site (readthedocs.org), as it creates yet another platform for contributors to understand. Reducing the number of platforms has been a fairly clearly-stated goal of these recent conversations, as I've read it.

Despite agreeing that wikis are sometimes wonky, I thought of a solid reason against moving: we lose the Trac integration. A Trac wiki page can easily link to tickets and individual comments, and can use dynamic features such as lists of active tickets. These are useful and well-used features. I don't know what's best here, but thinking about the real loss associated with moving away from these features gives me pause.

Richard

> On Sep 27, 2016, at 5:58 PM, Michael Sloan <mgsloan at gmail.com> wrote:
> 
> 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
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs