How, precisely, can we improve?

Thu Sep 29 19:14:18 UTC 2016

I've spent some time thinking about how and what to synthesize from this conversation. Moritz has captured much of these ideas in the proposal he submitted. Thanks.

But that proposal tackles only one part of the problem: what to do in the future. It does not address the insufficiencies of the wiki as it now stands, and these drawbacks seem to be the dangling fibers of this thread. Two specific complaints are that (1) search engines still find out-of-date documentation and (2) the wiki is not discoverable. I agree with both of these, but I can't think of any (easy) way to help either one.

For (1), the "obvious" solution is to pull old pages. However, old pages still serve as useful documentary evidence when we need to revisit a decision made in the past. I think simply deleting out-of-date pages may lose useful info. Could we remove the pages from the wiki but keep them somewhere else, beyond the all-seeing eye of Google? Perhaps -- but where? I wouldn't want to keep it somewhere private, lest it be unavailable to the person that needs it. I think clearly labeling out-of-date info as such is the best compromise.

For (2), there is an index to the wiki: https://ghc.haskell.org/trac/ghc/wiki/TitleIndex   It's long and rambly, but may be of use. I agree that grepping would be nice. Does anyone know if there is a way to extract plaintext from a Trac wiki? I agree that making such a feature available would be helpful. In the future, though, even a git-backed collection will run into discoverability problems, unless someone continually keeps it organized. (It will be greppable, though.)

As to the point of shoring up existing infra vs. looking more broadly: I suppose I am interesting in shoring up the existing infra, but I'm considering "existing infra" to include all the platforms I'm aware of. This explicitly includes the idea of dropping, say, Trac entirely and moving exclusively to GitHub. I think that would be a terrible idea, but it's in scope in my thinking. What's *not* in scope (in my thinking) is the idea of creating new tools that do exactly what we want. We're all developers and can imagine wonderful things, but wonderful things do not come cheaply, and we are but poor.

So I'm at a loss of what to do about these remaining fibers. Concrete suggestions, anyone?

Richard

-=-=-=-=-=-=-=-=-=-=-
Richard A. Eisenberg
Asst. Prof. of Computer Science
Bryn Mawr College
Bryn Mawr, PA, USA
cs.brynmawr.edu/~rae <http://cs.brynmawr.edu/~rae>
> On Sep 29, 2016, at 7:37 AM, Takenobu Tani <takenobu.hs at gmail.com> wrote:
> 
> 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 <mailto:carter.schonwald at gmail.com>>:
> I like your perspective on this
> 
> 
> On Wednesday, September 28, 2016, Takenobu Tani <takenobu.hs at gmail.com <mailto: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 <http://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/ <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 <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 <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 <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 <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/9a684bc3/attachment-0001.html>