How, precisely, can we improve?

[Takenobu Tani]

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/20160928/d85b87e1/attachment.html>