How, precisely, can we improve?

Fri Sep 30 11:06:11 UTC 2016

Dear Takenobu,

may I politely direct you to https://github.com/ghc-proposals/ghc-proposals/pull/10,
and ask you to add your comments there as well, as that proposal tries to track these
changes in a central place through the new ghc-proposal process.

Cheers,
 Moritz

> On Sep 30, 2016, at 6:56 PM, Takenobu Tani <takenobu.hs at gmail.com> wrote:
> 
> Hi,
> 
> Richard said:
> (1) search engines still find out-of-date documentation
> (2) the wiki is not discoverable
> 
> I know trac is treasure house.
> And I realized old pages are valuable for decision.
> 
> 
> My concrete suggestion is here:
> 
> For (1):
> When we find out-of-date documentation, we directly modify head of the document.
> We manually insert a comment like "This content is out-of-date for GHC8.0".
> (New contributors easy can do it.)
> 
> For (2):
> We provide manually-written multiple indexes for different views on a portal page of the wiki site.
> Contributors could maintain each index themselves.
> (New comers will choose his favorite index for his exploring.)
> 
> Furthermore, we provide a simple search box for multiple wiki sites.
> (Please wait for a while. I'll prepare simple-conceptual demonstration with web.)
> 
> 
> Diversity is strength of Haskell community,
> Takenobu
> 
> 
> 2016-09-30 4:14 GMT+09:00 Richard Eisenberg <rae at cs.brynmawr.edu>:
> 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
> 
>> 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>:
>> 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
>> 
>> 
> 
> 
> _______________________________________________
> 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

————————————————— 
Moritz Angermann
+49 170 54 33 0 74
moritz at lichtzwerge.de

lichtzwerge GmbH
Raiffeisenstr. 8
93185 Michelsneukirchen

Amtsgericht Regensburg HRB 14723
Geschäftsführung: Moritz Angermann, Ralf Sangl
USt-Id: DE291948767

Diese E-Mail enthält vertrauliche und/oder rechtlich geschützte
Informationen. Wenn Sie nicht der richtige Adressat sind oder diese
E-Mail irrtümlich erhalten haben, informieren Sie bitte sofort den
Absender und vernichten Sie diese Mail.
Das unerlaubte Kopieren sowie die unbefugte Weitergabe dieser Mail
ist nicht gestattet.
This e-mail may contain confidential and/or privileged information.
If you are not the intended recipient (or have received this e-mail in
error) please notify the sender immediately and destroy this e-mail.
Any unauthorized copying, disclosure or distribution of the material in
this e-mail is strictly forbidden.