How, precisely, can we improve?

Thu Sep 29 11:37:29 UTC 2016

Hi Carter,

Thank you very much :)

We love haskell,
Takenobu

2016-09-28 22:29 GMT+09:00 Carter Schonwald <carter.schonwald at gmail.com>:

> I like your perspective on this
>
>
> On Wednesday, September 28, 2016, Takenobu Tani <takenobu.hs at gmail.com>
> wrote:
>
>> Apologies if I’m missing context.
>>
>>
>>
>> Potential contributors need information from wiki.
>>
>> I feel current wiki’s problems are following:
>>
>>
>>
>>   (a) reachability
>>
>>     "Where is the page I need?"
>>
>>
>>
>>   (b) outdated pages
>>
>>     "Is this page up-to-date?"
>>
>>
>>
>>   (c) update method
>>
>>     "How Can I update the page?"
>>
>>
>>
>>
>>
>> About (a):
>>
>>
>>
>> It's difficult to find pages they need. Maybe reasons are following:
>>
>>   * We have multiple wiki sites.
>>
>>   * Desired contents structure is different for each member.
>>
>>
>>
>> So single wiki site is not enough from latter.
>>
>>
>>
>> Therefore, what about "a search system for multiple wiki sites"?
>>
>>
>>
>>
>>
>> About (b):
>>
>>
>>
>> Haskell's evolution is fast.
>>
>> New contributor encounters sometimes outdated pages.
>>
>> But they don't still know how to correct them.
>>
>>
>>
>> Therefore, what about putting "outdated mark" to the page by them?
>>
>>
>>
>> They can easily contribute.
>>
>> And if possible, they send update request with any way.
>>
>> We’ll preferentially update many requested pages.
>>
>>
>>
>>
>>
>> About (c):
>>
>>
>>
>> We have multiple wiki sites. Someone is unfamiliar about them.
>>
>> Github is one of the solutions for new contents.
>>
>> But I don't have idea about this for current contents.
>>
>>
>>
>> Regards,
>>
>> Takenobu
>>
>>
>>
>> 2016-09-28 10:51 GMT+09:00 Richard Eisenberg <rae at cs.brynmawr.edu>:
>>
>>> 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
>>>
>>> _______________________________________________
>>> ghc-devs mailing list
>>> ghc-devs at haskell.org
>>> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>>>
>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20160929/8ec91913/attachment-0001.html>