Re: How, precisely, can we improve?

[Carter Schonwald]

Thank you so much. I know I've said it before.  But the slides / notes
you've taken the time to write and circulate before have been truely great.

How can I and others help encourage you and others to keep up the great
work on that side?

Good synthesis notes that help orientate new and old contributors for
systems they don't know or have forgotten is a powerful resource.

I hope my encouragement helps. But either way it's a skill / focus that
takes time to develop and is worth celebrating / thanking.

As always, happy to be a resource to help, but  to you Takenobu! :)

On Saturday, October 1, 2016, Takenobu Tani  wrote:

> Main discussion is here (https://github.com/ghc-
> proposals/ghc-proposals/pull/10).
>
>
> BTW, I prepared a conceptual web page about following.
>
> > Furthermore, we provide a simple search box for multiple wiki sites.
> > (Please wait for a while. I'll prepare simple-conceptual demonstration
> with web.)
>
>
> Here is a rapid prototyping for searching multiple wiki sites. [1]
>
>
> [1]: https://takenobu-hs.github.io/haskell-wiki-search
>
> Regards,
> Takenobu
>
>
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: How, precisely, can we improve?

[Takenobu Tani]

Main discussion is here (
https://github.com/ghc-proposals/ghc-proposals/pull/10).


BTW, I prepared a conceptual web page about following.

> Furthermore, we provide a simple search box for multiple wiki sites.
> (Please wait for a while. I'll prepare simple-conceptual demonstration
with web.)


Here is a rapid prototyping for searching multiple wiki sites. [1]


[1]: https://takenobu-hs.github.io/haskell-wiki-search

Regards,
Takenobu
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: How, precisely, can we improve?

[Bardur Arantsson]

On 2016-09-30 19:26, Carter Schonwald wrote:
> We all do!.

I dont.

(Sorry, just had to put that Monty Python joke in there. At least I
*think* it was MP?)

Obviously, yes, we all *really* *REALLY* like Haskell, otherwise we
wouldn't be arguing about it, would we? ;)

Regards,

___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: How, precisely, can we improve?

[Carter Schonwald]

We all do!.

And I really appreciate your clear positive suggestions around "what are we
trying to understand or ask our selves"

no matter what conclusions we come to this day / month / year, its
something we will need to revisit (and should) every once in a while.
change happens, as does "growth" (for various notions of growth :) )

On Sep 29, 2016 7:37 AM, "Takenobu Tani"  wrote:

> Hi Carter,
>
> Thank you very much :)
>
> We love haskell,
> Takenobu
>
>
> 2016-09-28 22:29 GMT+09:00 Carter Schonwald :
>
>> I like your perspective on this
>>
>>
>> On Wednesday, September 28, 2016, Takenobu Tani 
>> 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 :
>>>
 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  wrote:
 >
 > On Tue, Sep 27, 2016 at 9:18 AM, Eric Seidel  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 

Re: How, precisely, can we improve?

[Takenobu Tani]

Dear Moritz,

Oh, thank you for teaching me.
I'll write to it.

Thanks,
Takenobu


2016-09-30 20:06 GMT+09:00 Moritz Angermann :

> 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 
> 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 :
> > 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 
> wrote:
> >>
> >> Hi Carter,
> >>
> >> Thank you very much :)
> >>
> >> We love haskell,
> >> Takenobu
> >>
> >>
> >> 2016-09-28 22:29 GMT+09:00 Carter Schonwald  >:
> >> I like your perspective on this
> >>
> >>
> >> On Wednesday, September 28, 2016, Takenobu Tani 
> 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):
> >>
> >>

Re: How, precisely, can we improve?

[Takenobu Tani]

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 :

> 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  wrote:
>
> Hi Carter,
>
> Thank you very much :)
>
> We love haskell,
> Takenobu
>
>
> 2016-09-28 22:29 GMT+09:00 Carter Schonwald :
>
>> I like your perspective on this
>>
>>
>> On Wednesday, September 28, 2016, Takenobu Tani 
>> 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.
>>>
>>>
>>>

Re: How, precisely, can we improve?

[Tom Murphy]

On Fri, Sep 30, 2016 at 4:14 AM, Richard Eisenberg 
wrote:

> 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.
>
>
+1 to keeping (maybe with "this is old" labels): I would much rather have a
page with a series of pointers to how something was done a few years ago
than to have no information at all.

I'd also like to +1 the fact that having Trac's up-to-date ticket labels
(e.g. crossed-out links for completed tickets) is invaluable.

Tom



> 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  wrote:
>
> Hi Carter,
>
> Thank you very much :)
>
> We love haskell,
> Takenobu
>
>
> 2016-09-28 22:29 GMT+09:00 Carter Schonwald :
>
>> I like your perspective on this
>>
>>
>> On Wednesday, September 28, 2016, Takenobu Tani 
>> 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 :
>>>
 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 

Re: How, precisely, can we improve?

[Richard Eisenberg]

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  wrote:
> 
> Hi Carter,
> 
> Thank you very much :)
> 
> We love haskell,
> Takenobu
> 
> 
> 2016-09-28 22:29 GMT+09:00 Carter Schonwald  >:
> I like your perspective on this
> 
> 
> On Wednesday, September 28, 2016, Takenobu Tani  > 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 >:
> 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 

Re: How, precisely, can we improve?

[Takenobu Tani]

Hi Carter,

Thank you very much :)

We love haskell,
Takenobu


2016-09-28 22:29 GMT+09:00 Carter Schonwald :

> I like your perspective on this
>
>
> On Wednesday, September 28, 2016, Takenobu Tani 
> 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 :
>>
>>> 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  wrote:
>>> >
>>> > On Tue, Sep 27, 2016 at 9:18 AM, Eric Seidel  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 

Re: How, precisely, can we improve?

[Moritz Angermann]

Friends,

after the recent discussion here and on #ghc, I’ve taken
the liberty to extract a small part of this into a
proposal[1].  In essence this does not cover *all* of the
wiki, but the commentary and documentation part, after
Herbert mentioned that would be something he could see
happening.

So let’s see if we can make this happen!

Cheers,
 Moritz

--
[1]: https://github.com/ghc-proposals/ghc-proposals/pull/10
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: How, precisely, can we improve?

[Alan & Kim Zimmerman]

For me the biggest problem is that each of the three Wiki's has a different
markup syntax.

So the mental motivation to do anything is tempered by having to look up
everything to make sure you are using the right markup for *this* Wiki.

Reducing it to one, wherever it is, would help a lot.

Alan
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: How, precisely, can we improve?

[Herbert Valerio Riedel]

On 2016-09-28 at 03:51:22 +0200, Richard Eisenberg wrote:

[...]

> 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.

I'd like to emphasize this point; Trac's main strength, design
philosophy, and selling point is its tight integration between SCM, Wiki
and Issue tracking and resulting synergies (same markup features,
extensions, syntax usable seamless), whereas the issue tracking part is
its strongest feature.

If you rip away its Wiki (and replace it by something
decoupled/non-integrated as e.g. GitHub's Git-backed Wiki[1]), you
weaken it to the point where it becomes quite harder to argue to keep
Trac at all. It's already sub-optimal we spread discussions/information
across Trac and Phabricator (you often have to read both, the Diff
discussions and the associated Trac ticket discussion to get the full
picture); I doubt a 3rd more or less isolated tool which weakens
cohesion would improve things.


 [1]: Personally, I consider GitHub's Wiki quite weak and inconvenient
  to use.  It's stylesheet is not as optimised as Trac's and
  structuring the content is also significantly worse than with
  Trac. And finally GH-flavoured Markdown is very limiting compared
  to Trac's rich extensible wiki syntax; Github's Wiki doesn't even
  recognize #123 or Git-shas like 993d20a2e9b8fb29a (and then
  provide mouse-over hoover texts with a title of the respective
  referenced commit or ticket); you have to paste full urls and
  manually include a title.

  So IMO Github's wiki is not suitable for GHC's use at all.

  A highly customized/forked Gitit instance, however, may be a more
  reasonable alternative, but then the question is who is gonna
  customize, implement and maintain it. Or we can drop the idea of a
  wiki altogether, and go for statically generated docs. Then we
  could just keep the wiki-content as restructedText (which btw is
  more expressive and extensible than .md) and have sphinx generated
  output. But then that's a totally different medium compared to a
  Wiki...

  However, I'm still missing a compelling reason in this discussion
  to justify the cost of changing the status-quo.

___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: How, precisely, can we improve?

[Christopher Allen]

I was thinking of what Richard was describing as shoring up the
insufficiencies of the existing infra, rather than something to be
directly targeted in any possible alternative.

Hypothetically could be made automatic or a git hook, if you wanted
things like last-modified timestamps injected into the documents. I
don't have strong feelings on this other than to say that there are
simpler ways to represent and serve documentation that let people use
whatever layer on top they want.

For example, if someone _did_ want the readthedocs specifically, they
could mirror the repo into the RTD branch and point it at the docs
directory or similar.

Git repos mean not being blocked by trac slowness/downtime, the
content being more widely mirrored, all kinds of nice to be
potentially had.

On Thu, Sep 29, 2016 at 12:01 AM, Moritz Angermann
 wrote:
> That is an interesting way to interact with the wiki, I had
> never thought about using it that way!
>
> So what you are proposing is a version controlled text based
> documentation system, precisely you can download the wiki and
> use your own cli/editor finding/indexing tools on it?
>
> This would of course be covered by almost any of the static
> side generation tools that work off of git I assume.
>
> I’m still uncertain how to accommodate Richards dynamic features
> into this? And I believe he’s not the only one who relies on them?
>
> Regarding the stale wiki page issue, scanning the history for
> files could potentially provide a list of “old” items, and
> eventually one could just delete them from master (automatically?)
>
>
>> On Sep 29, 2016, at 12:37 PM, Christopher Allen  wrote:
>>
>> Makes sense, no problem!
>>
>> I think my main personal complaints with docs have been:
>>
>> Poor discoverability — neither wikis nor search solve this, I want a
>> dir listing.
>>
>> Slow search — almost every wiki has slow search. bouncing out to
>> google is annoying. just let me grep.
>>
>> Broken links — this is particularly annoying as unis like to shut down
>> student accounts hosting papers. I had to do some archaeology on an
>> obscure Chinese FTP server to find some of Don Stewart's papers and
>> slides recently.
>>
>> I believe there can be a convincing solution to all of this and more.
>>
>> On Wed, Sep 28, 2016 at 11:33 PM, Moritz Angermann
>>  wrote:
>>> Chris,
>>>
>>> I’m all in favor of a better system! My only intention was to point
>>> to a solution that might help with the current system, right now.
>>>
>>> I’ve come to use that feature quite frequently even outside of this
>>> specific use case, as many of the results are often full of
>>> interesting yet stale information.
>>>
>>> Anyhow, I don’t want to obligate anyone to do anything, and if this
>>> was perceived that way, I’m truly sorry.
>>>
>>> Cheers,
>>> Moritz
>>>
 On Sep 29, 2016, at 12:24 PM, Christopher Allen  wrote:

 Why not just do the better thing to begin with rather than obligating
 people to think to use this feature? Most, even those who know it's an
 option, aren't going to think to do this in the heat of trying to
 track down an answer to something.

 On Wed, Sep 28, 2016 at 11:08 PM, Moritz Angermann
  wrote:
> Just a quick note: Google provides the “Date range” filter found under
> search options. This allows to narrow down the date range.
>
>> On Sep 29, 2016, at 11:55 AM, Bardur Arantsson  
>> wrote:
>>
>> On 2016-09-29 04:43, Richard Eisenberg wrote:
>>> Here's a pre-proposal (which could be formalized into a proper proposal)
>>> to address the wiki discussion:
>>>
>>> - Configure the wiki to display the date of last edit prominently.
>>>
>>> - If the date of last edit is sufficiently long ago (1 year?) loudly
>>> warn the reader that the content may be out-of-date.
>>>
>>
>> I see at least one major issue with this: Search engines don't care if
>> you write "THIS MAY BE OUT OF DATE" on the page. It's a perennial
>> problem that search engines keep linking out of date material just
>> because such material tends to be linked more (simply because of age).
>>
>> There are few tings as infuriating as going through a bunch of search
>> results and getting pages from 10 years ago.
>>
>> Regards,
>>
>> ___
>> ghc-devs mailing list
>> ghc-devs@haskell.org
>> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>
> ___
> ghc-devs mailing list
> ghc-devs@haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs



 --
 Chris Allen
 Currently working on http://haskellbook.com
>>>
>>
>>
>>
>> --
>> Chris Allen
>> Currently working on http://haskellbook.com
>



-- 

Re: How, precisely, can we improve?

[Moritz Angermann]

That is an interesting way to interact with the wiki, I had
never thought about using it that way!

So what you are proposing is a version controlled text based
documentation system, precisely you can download the wiki and
use your own cli/editor finding/indexing tools on it?

This would of course be covered by almost any of the static
side generation tools that work off of git I assume.

I’m still uncertain how to accommodate Richards dynamic features
into this? And I believe he’s not the only one who relies on them?

Regarding the stale wiki page issue, scanning the history for
files could potentially provide a list of “old” items, and
eventually one could just delete them from master (automatically?)


> On Sep 29, 2016, at 12:37 PM, Christopher Allen  wrote:
> 
> Makes sense, no problem!
> 
> I think my main personal complaints with docs have been:
> 
> Poor discoverability — neither wikis nor search solve this, I want a
> dir listing.
> 
> Slow search — almost every wiki has slow search. bouncing out to
> google is annoying. just let me grep.
> 
> Broken links — this is particularly annoying as unis like to shut down
> student accounts hosting papers. I had to do some archaeology on an
> obscure Chinese FTP server to find some of Don Stewart's papers and
> slides recently.
> 
> I believe there can be a convincing solution to all of this and more.
> 
> On Wed, Sep 28, 2016 at 11:33 PM, Moritz Angermann
>  wrote:
>> Chris,
>> 
>> I’m all in favor of a better system! My only intention was to point
>> to a solution that might help with the current system, right now.
>> 
>> I’ve come to use that feature quite frequently even outside of this
>> specific use case, as many of the results are often full of
>> interesting yet stale information.
>> 
>> Anyhow, I don’t want to obligate anyone to do anything, and if this
>> was perceived that way, I’m truly sorry.
>> 
>> Cheers,
>> Moritz
>> 
>>> On Sep 29, 2016, at 12:24 PM, Christopher Allen  wrote:
>>> 
>>> Why not just do the better thing to begin with rather than obligating
>>> people to think to use this feature? Most, even those who know it's an
>>> option, aren't going to think to do this in the heat of trying to
>>> track down an answer to something.
>>> 
>>> On Wed, Sep 28, 2016 at 11:08 PM, Moritz Angermann
>>>  wrote:
 Just a quick note: Google provides the “Date range” filter found under
 search options. This allows to narrow down the date range.
 
> On Sep 29, 2016, at 11:55 AM, Bardur Arantsson  
> wrote:
> 
> On 2016-09-29 04:43, Richard Eisenberg wrote:
>> Here's a pre-proposal (which could be formalized into a proper proposal)
>> to address the wiki discussion:
>> 
>> - Configure the wiki to display the date of last edit prominently.
>> 
>> - If the date of last edit is sufficiently long ago (1 year?) loudly
>> warn the reader that the content may be out-of-date.
>> 
> 
> I see at least one major issue with this: Search engines don't care if
> you write "THIS MAY BE OUT OF DATE" on the page. It's a perennial
> problem that search engines keep linking out of date material just
> because such material tends to be linked more (simply because of age).
> 
> There are few tings as infuriating as going through a bunch of search
> results and getting pages from 10 years ago.
> 
> Regards,
> 
> ___
> ghc-devs mailing list
> ghc-devs@haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
 
 ___
 ghc-devs mailing list
 ghc-devs@haskell.org
 http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>>> 
>>> 
>>> 
>>> --
>>> Chris Allen
>>> Currently working on http://haskellbook.com
>> 
> 
> 
> 
> -- 
> Chris Allen
> Currently working on http://haskellbook.com

___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: How, precisely, can we improve?

[Christopher Allen]

Makes sense, no problem!

I think my main personal complaints with docs have been:

Poor discoverability — neither wikis nor search solve this, I want a
dir listing.

Slow search — almost every wiki has slow search. bouncing out to
google is annoying. just let me grep.

Broken links — this is particularly annoying as unis like to shut down
student accounts hosting papers. I had to do some archaeology on an
obscure Chinese FTP server to find some of Don Stewart's papers and
slides recently.

I believe there can be a convincing solution to all of this and more.

On Wed, Sep 28, 2016 at 11:33 PM, Moritz Angermann
 wrote:
> Chris,
>
> I’m all in favor of a better system! My only intention was to point
> to a solution that might help with the current system, right now.
>
> I’ve come to use that feature quite frequently even outside of this
> specific use case, as many of the results are often full of
> interesting yet stale information.
>
> Anyhow, I don’t want to obligate anyone to do anything, and if this
> was perceived that way, I’m truly sorry.
>
> Cheers,
>  Moritz
>
>> On Sep 29, 2016, at 12:24 PM, Christopher Allen  wrote:
>>
>> Why not just do the better thing to begin with rather than obligating
>> people to think to use this feature? Most, even those who know it's an
>> option, aren't going to think to do this in the heat of trying to
>> track down an answer to something.
>>
>> On Wed, Sep 28, 2016 at 11:08 PM, Moritz Angermann
>>  wrote:
>>> Just a quick note: Google provides the “Date range” filter found under
>>> search options. This allows to narrow down the date range.
>>>
 On Sep 29, 2016, at 11:55 AM, Bardur Arantsson  
 wrote:

 On 2016-09-29 04:43, Richard Eisenberg wrote:
> Here's a pre-proposal (which could be formalized into a proper proposal)
> to address the wiki discussion:
>
> - Configure the wiki to display the date of last edit prominently.
>
> - If the date of last edit is sufficiently long ago (1 year?) loudly
> warn the reader that the content may be out-of-date.
>

 I see at least one major issue with this: Search engines don't care if
 you write "THIS MAY BE OUT OF DATE" on the page. It's a perennial
 problem that search engines keep linking out of date material just
 because such material tends to be linked more (simply because of age).

 There are few tings as infuriating as going through a bunch of search
 results and getting pages from 10 years ago.

 Regards,

 ___
 ghc-devs mailing list
 ghc-devs@haskell.org
 http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>>>
>>> ___
>>> ghc-devs mailing list
>>> ghc-devs@haskell.org
>>> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>>
>>
>>
>> --
>> Chris Allen
>> Currently working on http://haskellbook.com
>



-- 
Chris Allen
Currently working on http://haskellbook.com
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: How, precisely, can we improve?

[Moritz Angermann]

Chris,

I’m all in favor of a better system! My only intention was to point
to a solution that might help with the current system, right now.

I’ve come to use that feature quite frequently even outside of this
specific use case, as many of the results are often full of
interesting yet stale information.

Anyhow, I don’t want to obligate anyone to do anything, and if this
was perceived that way, I’m truly sorry.

Cheers,
 Moritz

> On Sep 29, 2016, at 12:24 PM, Christopher Allen  wrote:
> 
> Why not just do the better thing to begin with rather than obligating
> people to think to use this feature? Most, even those who know it's an
> option, aren't going to think to do this in the heat of trying to
> track down an answer to something.
> 
> On Wed, Sep 28, 2016 at 11:08 PM, Moritz Angermann
>  wrote:
>> Just a quick note: Google provides the “Date range” filter found under
>> search options. This allows to narrow down the date range.
>> 
>>> On Sep 29, 2016, at 11:55 AM, Bardur Arantsson  wrote:
>>> 
>>> On 2016-09-29 04:43, Richard Eisenberg wrote:
 Here's a pre-proposal (which could be formalized into a proper proposal)
 to address the wiki discussion:
 
 - Configure the wiki to display the date of last edit prominently.
 
 - If the date of last edit is sufficiently long ago (1 year?) loudly
 warn the reader that the content may be out-of-date.
 
>>> 
>>> I see at least one major issue with this: Search engines don't care if
>>> you write "THIS MAY BE OUT OF DATE" on the page. It's a perennial
>>> problem that search engines keep linking out of date material just
>>> because such material tends to be linked more (simply because of age).
>>> 
>>> There are few tings as infuriating as going through a bunch of search
>>> results and getting pages from 10 years ago.
>>> 
>>> Regards,
>>> 
>>> ___
>>> ghc-devs mailing list
>>> ghc-devs@haskell.org
>>> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>> 
>> ___
>> ghc-devs mailing list
>> ghc-devs@haskell.org
>> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
> 
> 
> 
> -- 
> Chris Allen
> Currently working on http://haskellbook.com

___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: How, precisely, can we improve?

[Moritz Angermann]

Just a quick note: Google provides the “Date range” filter found under
search options. This allows to narrow down the date range.

> On Sep 29, 2016, at 11:55 AM, Bardur Arantsson  wrote:
> 
> On 2016-09-29 04:43, Richard Eisenberg wrote:
>> Here's a pre-proposal (which could be formalized into a proper proposal)
>> to address the wiki discussion:
>> 
>> - Configure the wiki to display the date of last edit prominently.
>> 
>> - If the date of last edit is sufficiently long ago (1 year?) loudly
>> warn the reader that the content may be out-of-date.
>> 
> 
> I see at least one major issue with this: Search engines don't care if
> you write "THIS MAY BE OUT OF DATE" on the page. It's a perennial
> problem that search engines keep linking out of date material just
> because such material tends to be linked more (simply because of age).
> 
> There are few tings as infuriating as going through a bunch of search
> results and getting pages from 10 years ago.
> 
> Regards,
> 
> ___
> ghc-devs mailing list
> ghc-devs@haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: How, precisely, can we improve?

[Christopher Allen]

I tend to agree, particularly as it would permit automated processing
and conversion of the documentation much more readily than a website
really ever has.

I don't think I've ever used a public wiki that enforced broken link
checking, whereas that's a sundry CI check for static markdown
documentation.

Markdown files can become anything somebody wants, including a web
server hosting it as HTML documentation that looks however they want.

This approach doesn't prevent separating docs for the community vs.
implementors either. Just a subdirectory if you wanted.

On Wed, Sep 28, 2016 at 9:30 PM, Manuel M T Chakravarty
<c...@justtesting.org> wrote:
> Michael’s arguments are compelling.
>
> Manuel
>
> Simon Peyton Jones via ghc-devs <ghc-devs@haskell.org>:
>
> Interesting article.  Michael suggests using markdown in repo-controlled
> files rather than a wiki.  I can see the force of that. Maybe we should
> consider it.
>
> Simon
>
> From: Alan & Kim Zimmerman [mailto:alan.z...@gmail.com]
> Sent: 27 September 2016 15:54
> To: Simon Peyton Jones <simo...@microsoft.com>
> Cc: Sven Panne <svenpa...@gmail.com>; ghc-devs <ghc-devs@haskell.org>
> Subject: Re: How, precisely, can we improve?
>
>
> I think this is relevant to the dicussion:
> http://www.yesodweb.com/blog/2015/08/thoughts-on-documentation
>
> Alan
>
> On Tue, Sep 27, 2016 at 4:22 PM, Simon Peyton Jones via ghc-devs
> <ghc-devs@haskell.org> wrote:
>
> We currently have *3* wikis:
>
> https://wiki.haskell.org/Haskell
> https://ghc.haskell.org/trac/ghc
> https://phabricator.haskell.org/w/
>
> I didn’t even know about  the third of these, but the first two have clearly
> differentiated goals:
>
> ·https://wiki.haskell.org/Haskell is about user-facing, and often
> user-generated, documentation.  Guidance about improving performance,
> programming idioms, tutorials etc.
>
> ·https://ghc.haskell.org/trac/ghc is about GHC’s implementation,
> oriented to people who want to understand how GHC works, and how to modify
> it.
>
>
> I think this separation is actually quite helpful.
>
> I agree with what you and others say about the difficulty of keeping wikis
> organised. But that’s not primarily a technology issue: there is a genuinely
> difficult challenge here.  How do you build and maintain up-to-date,
> navigable, well-organised information about a large, complex, and rapidly
> changing artefact like GHC?  A wiki is one approach that has the merit that
> anyone can improve it; control is not centralised.  But I’d love there to be
> other, better solutions.
>
> Simon
>
> From: ghc-devs [mailto:ghc-devs-boun...@haskell.org] On Behalf Of Sven Panne
> Sent: 27 September 2016 08:46
> To: ghc-devs <ghc-devs@haskell.org>
> Subject: Re: How, precisely, can we improve?
>
> Just a remark from my side: The documentation/tooling landscape is a bit
> more fragmented than it needs to be IMHO. More concretely:
>
>* We currently have *3* wikis:
>
> https://wiki.haskell.org/Haskell
> https://ghc.haskell.org/trac/ghc
> https://phabricator.haskell.org/w/
>
>
>  It's clear to me that they have different emphases and different
> origins, but in the end this results in valuable information being scattered
> around. Wikis in general are already quite hard to navigate (due to their
> inherent chaotic "structure"), so having 3 of them makes things even worse.
> It would be great to have *the* single Haskell Wiki directly on haskell.org
> in an easily reachable place.
>
>* To be an active Haskell community member, you need quite a few
> different logins: Some for the Wikis mentioned above, one for Hackage,
> another one for Phabricator, perhaps an SSH key here and there...
> Phabricator is a notable exception: It accepts your GitHub/Google+/...
> logins. It would be great if the other parts of the Haskell ecosystem
> accepted those kinds of logins, too.
>
>* https://haskell-lang.org/ has great stuff on it, but its relationship
> to haskell.org is unclear to me. Their "documentation" sub-pages look
> extremely similar, but haskell-lang.org has various (great!) tutorials and a
> nice overview of common libraries on it. From an external POV it seems to me
> that haskell-lang.org should be seamlessly integrated into haskell.org, i.e.
> merged into it. Having an endless sea of links on haskell.org is not the
> same as having content nicely integrated into it, sorted by topic, etc.
>
> All those points are not show-stoppers for people trying to be more active
> in the Haskell community, but nevertheless they make things harder than they
> need to be, so I fear

Re: How, precisely, can we improve?

[Richard Eisenberg]

Here's a pre-proposal (which could be formalized into a proper proposal) to 
address the wiki discussion:

- Configure the wiki to display the date of last edit prominently.

- If the date of last edit is sufficiently long ago (1 year?) loudly warn the 
reader that the content may be out-of-date.

And that's it! I think that solves the problem. The reason this solves the 
problem is that the ghc-proposals process is already en route to providing the 
git-backed files that have been floated as the alternative to a wiki. Thus, 
language features, etc., will be memorialized through the ghc-proposals 
process. As I understand it, that process already requires the proposal to be 
updated to a description of the feature as the feature is implemented and 
refined. We will be left with a nice git repo of feature descriptions.

The wiki can remain as a place for less permanent discussions (such as 
pre-proposals) or pages that use the nice dynamic features of Trac.

Is this proposal possible to implement? Does it solve the wiki problem 
sufficiently?

Sometimes, solutions are easy. :)
Richard


> On Sep 28, 2016, at 10:30 PM, Manuel M T Chakravarty <c...@justtesting.org> 
> wrote:
> 
> Michael’s arguments are compelling.
> 
> Manuel
> 
>> Simon Peyton Jones via ghc-devs <ghc-devs@haskell.org 
>> <mailto:ghc-devs@haskell.org>>:
>> 
>> Interesting article.  Michael suggests using markdown in repo-controlled 
>> files rather than a wiki.  I can see the force of that. Maybe we should 
>> consider it.
>>  
>> Simon
>>   <>
>> From: Alan & Kim Zimmerman [mailto:alan.z...@gmail.com 
>> <mailto:alan.z...@gmail.com>] 
>> Sent: 27 September 2016 15:54
>> To: Simon Peyton Jones <simo...@microsoft.com <mailto:simo...@microsoft.com>>
>> Cc: Sven Panne <svenpa...@gmail.com <mailto:svenpa...@gmail.com>>; ghc-devs 
>> <ghc-devs@haskell.org <mailto:ghc-devs@haskell.org>>
>> Subject: Re: How, precisely, can we improve?
>>  
>> I think this is relevant to the dicussion: 
>> http://www.yesodweb.com/blog/2015/08/thoughts-on-documentation 
>> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.yesodweb.com%2Fblog%2F2015%2F08%2Fthoughts-on-documentation=01%7C01%7Csimonpj%40microsoft.com%7C7ff5e6e47ba5499a774308d3e6e631c2%7C72f988bf86f141af91ab2d7cd011db47%7C1=uXvFVL2YlOPej5%2Brxms7oUL91OD%2FpqDD9VLaOYtL%2FjQ%3D=0>
>> Alan
>>  
>> On Tue, Sep 27, 2016 at 4:22 PM, Simon Peyton Jones via ghc-devs 
>> <ghc-devs@haskell.org <mailto:ghc-devs@haskell.org>> wrote:
>> We currently have *3* wikis:
>>  
>> https://wiki.haskell.org/Haskell 
>> <https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=fxYacdt9XklXJaGetQABBI%2BG3IgnlJmB2r1EL54I1HU%3D=0>
>> https://ghc.haskell.org/trac/ghc <https://ghc.haskell.org/trac/ghc>
>> https://phabricator.haskell.org/w/ 
>> <https://phabricator.haskell.org/w/>
>>  
>> I didn’t even know about  the third of these, but the first two have clearly 
>> differentiated goals:
>> ·https://wiki.haskell.org/Haskell 
>> <https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=fxYacdt9XklXJaGetQABBI%2BG3IgnlJmB2r1EL54I1HU%3D=0>
>>  is about user-facing, and often user-generated, documentation.  Guidance 
>> about improving performance, programming idioms, tutorials etc.
>> 
>> ·https://ghc.haskell.org/trac/ghc <https://ghc.haskell.org/trac/ghc> 
>> is about GHC’s implementation, oriented to people who want to understand how 
>> GHC works, and how to modify it.
>> 
>>  
>> I think this separation is actually quite helpful.
>>  
>> I agree with what you and others say about the difficulty of keeping wikis 
>> organised. But that’s not primarily a technology issue: there is a genuinely 
>> difficult challenge here.  How do you build and maintain up-to-date, 
>> navigable, well-organised information about a large, complex, and rapidly 
>> changing artefact like GHC?  A wiki is one approach that has the merit that 
>> anyone can improve it; control is not centralised.  But I’d love there to be 
>> other, better solutions.
>>  
>> Simon
>>   <>
>> From: ghc-devs [mailto:ghc-devs-boun...@haskell.org 
>> <mailto:ghc-devs-boun...@haskell.org>] On Behalf Of Sven Panne
>> Sent: 2

Re: How, precisely, can we improve?

[Manuel M T Chakravarty]

Michael’s arguments are compelling.

Manuel

> Simon Peyton Jones via ghc-devs <ghc-devs@haskell.org>:
> 
> Interesting article.  Michael suggests using markdown in repo-controlled 
> files rather than a wiki.  I can see the force of that. Maybe we should 
> consider it.
>  
> Simon
>   <>
> From: Alan & Kim Zimmerman [mailto:alan.z...@gmail.com] 
> Sent: 27 September 2016 15:54
> To: Simon Peyton Jones <simo...@microsoft.com>
> Cc: Sven Panne <svenpa...@gmail.com>; ghc-devs <ghc-devs@haskell.org>
> Subject: Re: How, precisely, can we improve?
>  
> I think this is relevant to the dicussion: 
> http://www.yesodweb.com/blog/2015/08/thoughts-on-documentation 
> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.yesodweb.com%2Fblog%2F2015%2F08%2Fthoughts-on-documentation=01%7C01%7Csimonpj%40microsoft.com%7C7ff5e6e47ba5499a774308d3e6e631c2%7C72f988bf86f141af91ab2d7cd011db47%7C1=uXvFVL2YlOPej5%2Brxms7oUL91OD%2FpqDD9VLaOYtL%2FjQ%3D=0>
> Alan
>  
> On Tue, Sep 27, 2016 at 4:22 PM, Simon Peyton Jones via ghc-devs 
> <ghc-devs@haskell.org <mailto:ghc-devs@haskell.org>> wrote:
> We currently have *3* wikis:
>  
> https://wiki.haskell.org/Haskell 
> <https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=fxYacdt9XklXJaGetQABBI%2BG3IgnlJmB2r1EL54I1HU%3D=0>
> https://ghc.haskell.org/trac/ghc <https://ghc.haskell.org/trac/ghc>
> https://phabricator.haskell.org/w/ 
> <https://phabricator.haskell.org/w/>
>  
> I didn’t even know about  the third of these, but the first two have clearly 
> differentiated goals:
> ·https://wiki.haskell.org/Haskell 
> <https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=fxYacdt9XklXJaGetQABBI%2BG3IgnlJmB2r1EL54I1HU%3D=0>
>  is about user-facing, and often user-generated, documentation.  Guidance 
> about improving performance, programming idioms, tutorials etc.
> 
> ·https://ghc.haskell.org/trac/ghc <https://ghc.haskell.org/trac/ghc> 
> is about GHC’s implementation, oriented to people who want to understand how 
> GHC works, and how to modify it.
> 
>  
> I think this separation is actually quite helpful.
>  
> I agree with what you and others say about the difficulty of keeping wikis 
> organised. But that’s not primarily a technology issue: there is a genuinely 
> difficult challenge here.  How do you build and maintain up-to-date, 
> navigable, well-organised information about a large, complex, and rapidly 
> changing artefact like GHC?  A wiki is one approach that has the merit that 
> anyone can improve it; control is not centralised.  But I’d love there to be 
> other, better solutions.
>  
> Simon
>   <>
> From: ghc-devs [mailto:ghc-devs-boun...@haskell.org 
> <mailto:ghc-devs-boun...@haskell.org>] On Behalf Of Sven Panne
> Sent: 27 September 2016 08:46
> To: ghc-devs <ghc-devs@haskell.org <mailto:ghc-devs@haskell.org>>
> Subject: Re: How, precisely, can we improve?
>  
> Just a remark from my side: The documentation/tooling landscape is a bit more 
> fragmented than it needs to be IMHO. More concretely:
>  
>* We currently have *3* wikis:
>  
> https://wiki.haskell.org/Haskell 
> <https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=fxYacdt9XklXJaGetQABBI%2BG3IgnlJmB2r1EL54I1HU%3D=0>
> https://ghc.haskell.org/trac/ghc <https://ghc.haskell.org/trac/ghc>
> https://phabricator.haskell.org/w/ 
> <https://phabricator.haskell.org/w/>
>  
>  
>  It's clear to me that they have different emphases and different 
> origins, but in the end this results in valuable information being scattered 
> around. Wikis in general are already quite hard to navigate (due to their 
> inherent chaotic "structure"), so having 3 of them makes things even worse. 
> It would be great to have *the* single Haskell Wiki directly on haskell.org 
> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fhaskell.org=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=%2F8JlCXTwn%2FB8EyrW4BkY0QTS57X%2BFvs4BSXijqCbiNA%3D=0>
>  in an easily reachable place.
>  
>* To be an active Haskell community member, you need quite a few different 
> logins: Some for 

Re: How, precisely, can we improve?

[Carter Schonwald]

I like your perspective on this

On Wednesday, September 28, 2016, Takenobu Tani 
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  >:
>
>> 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 > > wrote:
>> >
>> > On Tue, Sep 27, 2016 at 9:18 AM, Eric Seidel > > 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) 

Re: How, precisely, can we improve?

[Takenobu Tani]

> Therefore, what about "a search system for multiple wiki sites"?

sorry, less information.

I mean like this.

Google search:
  "dependent haskell site:ghc.haskell.org/trac/ghc/wiki OR site:
wiki.haskell.org"

Regards,
Takenobu





2016-09-28 21:29 GMT+09:00 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 :
>
>> 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  wrote:
>> >
>> > On Tue, Sep 27, 2016 at 9:18 AM, Eric Seidel  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 

Re: How, precisely, can we improve?

[Nathan Bouscal]

On Mon, Sep 26, 2016 at 2:27 AM, Richard Eisenberg 
wrote:
>
>
> "Accept PRs on GitHub" *is* an answer to this question, but one we have
> revisited several times in recent memory. (I believe https://mail.haskell.
> org/pipermail/ghc-devs/2015-September/009744.html is the most recent.)
> Perhaps we can revisit this yet again, but it would be great if new
> technical content can be injected into the debate. I hope the rejection of
> the proposal linked there is not considered "dismissive", as the proposal
> generated vigorous debate -- the opposite of dismissiveness. (For what it's
> worth, I'm weakly in favor of accepting PRs on GitHub. However, I have no
> experience setting up or maintaining infrastructure for an open source
> project and have happily deferred to those who have such experience and who
> have come out against this idea.)
>

It may be worth pointing out that one of the most common objections in that
debate was GitHub's code review process, and in the time since that process
has been completely overhauled

.
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: 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  wrote:
> 
> On Tue, Sep 27, 2016 at 9:18 AM, Eric Seidel  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@haskell.org
>> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
> ___
> ghc-devs mailing list
> ghc-devs@haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: How, precisely, can we improve?

[Ben Gamari]

Eric Seidel  writes:

> Thanks for the link Alan.
>
> I can personally attest to being intimidated by GHC's wiki when I
> started contributing. I think having a review mechanism in place would
> have helped, because then you at least know that one or two other people
> think your content is clear.
>
> On a more minor note, I know the trac wiki has a history feature, but
> for some reason I find it much less useful than a git history. Perhaps
> this is just an issue of familiarity.
>
I agree, Trac's history feature is quite painful to use. I think that
the issue runs deeper than just familiarity. Being restricted comparing
revisions in a pairwise manner poses quite a usability problem. Git is
simply far more powerful in this area which is one of the advantages
that the new proposals process has relative to the Trac wiki.
Thankfully, this power isn't strictly necessary for most of the
non-proposal content currently in the Wiki.

Cheers,

- Ben



signature.asc
Description: PGP signature
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: How, precisely, can we improve?

[Richard Eisenberg]

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.

Is this perhaps an easy improvement we can enact?

Note that we’re already moving in this direction with ghc-proposals, which 
subsumes a large part of what the GHC dev wiki has been used for.

-=-=-=-=-=-=-=-=-=-=-
Richard A. Eisenberg
Asst. Prof. of Computer Science
Bryn Mawr College
Bryn Mawr, PA, USA
cs.brynmawr.edu/~rae

> On Sep 27, 2016, at 11:32 AM, Eric Seidel <e...@seidel.io> wrote:
> 
> Thanks for the link Alan.
> 
> I can personally attest to being intimidated by GHC's wiki when I
> started contributing. I think having a review mechanism in place would
> have helped, because then you at least know that one or two other people
> think your content is clear.
> 
> On a more minor note, I know the trac wiki has a history feature, but
> for some reason I find it much less useful than a git history. Perhaps
> this is just an issue of familiarity.
> 
> On Tue, Sep 27, 2016, at 07:54, Alan & Kim Zimmerman wrote:
>> I think this is relevant to the dicussion:
>> http://www.yesodweb.com/blog/2015/08/thoughts-on-documentation
>> 
>> Alan
>> 
>> On Tue, Sep 27, 2016 at 4:22 PM, Simon Peyton Jones via ghc-devs <
>> ghc-devs@haskell.org> wrote:
>> 
>>> We currently have *3* wikis:
>>> 
>>> 
>>> 
>>>https://wiki.haskell.org/Haskell
>>> <https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=fxYacdt9XklXJaGetQABBI%2BG3IgnlJmB2r1EL54I1HU%3D=0>
>>> 
>>>https://ghc.haskell.org/trac/ghc
>>> 
>>>https://phabricator.haskell.org/w/
>>> 
>>> 
>>> 
>>> I didn’t even know about  the third of these, but the first two have
>>> clearly differentiated goals:
>>> 
>>> ·https://wiki.haskell.org/Haskell
>>> <https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=fxYacdt9XklXJaGetQABBI%2BG3IgnlJmB2r1EL54I1HU%3D=0>
>>> is about user-facing, and often user-generated, documentation.  Guidance
>>> about improving performance, programming idioms, tutorials etc.
>>> 
>>> ·https://ghc.haskell.org/trac/ghc is about GHC’s implementation,
>>> oriented to people who want to understand how GHC works, and how to modify
>>> it.
>>> 
>>> 
>>> 
>>> I think this separation is actually quite helpful.
>>> 
>>> 
>>> 
>>> I agree with what you and others say about the difficulty of keeping wikis
>>> organised. But that’s not primarily a technology issue: there is a
>>> genuinely difficult challenge here.  How do you build and maintain
>>> up-to-date, navigable, well-organised information about a large, complex,
>>> and rapidly changing artefact like GHC?  A wiki is one approach that has
>>> the merit that anyone can improve it; control is not centralised.  But I’d
>>> love there to be other, better solutions.
>>> 
>>> 
>>> 
>>> Simon
>>> 
>>> 
>>> 
>>> *From:* ghc-devs [mailto:ghc-devs-boun...@haskell.org] *On Behalf Of *Sven
>>> Panne
>>> *Sent:* 27 September 2016 08:46
>>> *To:* ghc-devs <ghc-devs@haskell.org>
>>> *Subject:* Re: How, precisely, can we improve?
>>> 
>>> 
>>> 
>>> Just a remark from my side: The documentation/tooling landscape is a bit
>>> more fragmented than it needs to be IMHO. More concretely:
>>> 
>>> 
>>> 
>>>   * We currently have *3* wikis:
>>> 
>>> 
>>> 
>>>https://wiki.haskell.org/Haskell
>>> <https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2

RE: How, precisely, can we improve?

[Simon Peyton Jones via ghc-devs]

We currently have *3* wikis:


https://wiki.haskell.org/Haskell<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=fxYacdt9XklXJaGetQABBI%2BG3IgnlJmB2r1EL54I1HU%3D=0>
https://ghc.haskell.org/trac/ghc
https://phabricator.haskell.org/w/

I didn’t even know about  the third of these, but the first two have clearly 
differentiated goals:

·
https://wiki.haskell.org/Haskell<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=fxYacdt9XklXJaGetQABBI%2BG3IgnlJmB2r1EL54I1HU%3D=0>
 is about user-facing, and often user-generated, documentation.  Guidance about 
improving performance, programming idioms, tutorials etc.

·https://ghc.haskell.org/trac/ghc is about GHC’s implementation, 
oriented to people who want to understand how GHC works, and how to modify it.

I think this separation is actually quite helpful.

I agree with what you and others say about the difficulty of keeping wikis 
organised. But that’s not primarily a technology issue: there is a genuinely 
difficult challenge here.  How do you build and maintain up-to-date, navigable, 
well-organised information about a large, complex, and rapidly changing 
artefact like GHC?  A wiki is one approach that has the merit that anyone can 
improve it; control is not centralised.  But I’d love there to be other, better 
solutions.

Simon

From: ghc-devs [mailto:ghc-devs-boun...@haskell.org] On Behalf Of Sven Panne
Sent: 27 September 2016 08:46
To: ghc-devs <ghc-devs@haskell.org>
Subject: Re: How, precisely, can we improve?

Just a remark from my side: The documentation/tooling landscape is a bit more 
fragmented than it needs to be IMHO. More concretely:

   * We currently have *3* wikis:


https://wiki.haskell.org/Haskell<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.haskell.org%2FHaskell=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=fxYacdt9XklXJaGetQABBI%2BG3IgnlJmB2r1EL54I1HU%3D=0>
https://ghc.haskell.org/trac/ghc
https://phabricator.haskell.org/w/


 It's clear to me that they have different emphases and different origins, 
but in the end this results in valuable information being scattered around. 
Wikis in general are already quite hard to navigate (due to their inherent 
chaotic "structure"), so having 3 of them makes things even worse. It would be 
great to have *the* single Haskell Wiki directly on 
haskell.org<https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fhaskell.org=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=%2F8JlCXTwn%2FB8EyrW4BkY0QTS57X%2BFvs4BSXijqCbiNA%3D=0>
 in an easily reachable place.

   * To be an active Haskell community member, you need quite a few different 
logins: Some for the Wikis mentioned above, one for Hackage, another one for 
Phabricator, perhaps an SSH key here and there... Phabricator is a notable 
exception: It accepts your GitHub/Google+/... logins. It would be great if the 
other parts of the Haskell ecosystem accepted those kinds of logins, too.

   * 
https://haskell-lang.org/<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fhaskell-lang.org%2F=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=9ndNQVeDQy7lPb4qmn13k%2BAtztK8F9Hq%2B2jeXKm9YFU%3D=0>
 has great stuff on it, but its relationship to 
haskell.org<https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fhaskell.org=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=%2F8JlCXTwn%2FB8EyrW4BkY0QTS57X%2BFvs4BSXijqCbiNA%3D=0>
 is unclear to me. Their "documentation" sub-pages look extremely similar, but 
haskell-lang.org<https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fhaskell-lang.org=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=G9e%2BVDuPTtZHZl%2BGd2fFShUznQjDa158JENjoMiD0VY%3D=0>
 has various (great!) tutorials and a nice overview of common libraries on it. 
From an external POV it seems to me that 
haskell-lang.org<https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fhaskell-lang.org=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6aa6198%7C72f988bf86f141af91ab2d7cd011db47%7C1=G9e%2BVDuPTtZHZl%2BGd2fFShUznQjDa158JENjoMiD0VY%3D=0>
 should be seamlessly integrated into 
haskell.org<https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fhaskell.org=01%7C01%7Csimonpj%40microsoft.com%7C28109c89abb14244f87908d3e6

Re: How, precisely, can we improve?

[Sven Panne]

Just a remark from my side: The documentation/tooling landscape is a bit
more fragmented than it needs to be IMHO. More concretely:

   * We currently have *3* wikis:

https://wiki.haskell.org/Haskell
https://ghc.haskell.org/trac/ghc
https://phabricator.haskell.org/w/

 It's clear to me that they have different emphases and different
origins, but in the end this results in valuable information being
scattered around. Wikis in general are already quite hard to navigate (due
to their inherent chaotic "structure"), so having 3 of them makes things
even worse. It would be great to have *the* single Haskell Wiki directly on
haskell.org in an easily reachable place.

   * To be an active Haskell community member, you need quite a few
different logins: Some for the Wikis mentioned above, one for Hackage,
another one for Phabricator, perhaps an SSH key here and there...
Phabricator is a notable exception: It accepts your GitHub/Google+/...
logins. It would be great if the other parts of the Haskell ecosystem
accepted those kinds of logins, too.

   * https://haskell-lang.org/ has great stuff on it, but its relationship
to haskell.org is unclear to me. Their "documentation" sub-pages look
extremely similar, but haskell-lang.org has various (great!) tutorials and
a nice overview of common libraries on it. From an external POV it seems to
me that haskell-lang.org should be seamlessly integrated into haskell.org,
i.e. merged into it. Having an endless sea of links on haskell.org is not
the same as having content nicely integrated into it, sorted by topic, etc.

All those points are not show-stoppers for people trying to be more active
in the Haskell community, but nevertheless they make things harder than
they need to be, so I fear we lose people quite early. To draw an analogy:
As probably everybody who actively monitors their web shop/customer site
knows, even seemlingy small things moves customers totally away from your
site. One unclear payment form? The vast majority of your potential
customers aborts the purchase immediately and forever. One confusing
interstitial web page? Say goodbye to lots of people. One hard-to-find
button/link? A forced login/new account? => Commercial disaster, etc. etc.

Furthermore, I'm quite aware of the technical/social difficulties of my
proposals, but that shouldn't let us stop trying to improve...

Cheers,
   S.
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

How, precisely, can we improve?

[Richard Eisenberg]

Like many of you, I'm sure, I'm saddened by the occasional tone of the recent 
exchange about contributions to GHC.

I'd like to move the conversation forward -- and I'd like to do so on a 
technical basis.

So, I ask:
How, precisely, can we improve?

I think it would be best to have answers to this question start their own 
thread, as I expect several good answers to this question.

As I ask this, I am not making the assumption that we cannot, nor is this meant 
to be rhetorical. I am asking a question in search of precise, technical 
answers.

"Be more like Rust" is not an answer to this question, as it is imprecise. (I'm 
not at all maligning the overall goal of emulating a successful process. It's 
just that "be more like Rust" is not actionable.)

"Accept PRs on GitHub" *is* an answer to this question, but one we have 
revisited several times in recent memory. (I believe 
https://mail.haskell.org/pipermail/ghc-devs/2015-September/009744.html is the 
most recent.) Perhaps we can revisit this yet again, but it would be great if 
new technical content can be injected into the debate. I hope the rejection of 
the proposal linked there is not considered "dismissive", as the proposal 
generated vigorous debate -- the opposite of dismissiveness. (For what it's 
worth, I'm weakly in favor of accepting PRs on GitHub. However, I have no 
experience setting up or maintaining infrastructure for an open source project 
and have happily deferred to those who have such experience and who have come 
out against this idea.)

"Have process (X) for accepting new language features" *is* an answer to my 
question. This is in flight and I hope addresses the concern in the community. 
It seems to me that this step addresses the grievances described in "The 
Process" part of http://www.arcadianvisions.com/blog/2016/ghc-contributing.html

"Have a formal mentorship system" *is* another answer to my question, and one I 
think we can readily adopt. Can you (for all values of "you") suggest a 
concrete model with a link? It seems to me that folks who ask for help get the 
help they need. But this surely requires the courage and wherewithal to ask for 
the help. Perhaps there is a better way to advertise our availability and 
desire to mentor. I, personally, have onboarded (or attempted to) several 
contributors and enjoy doing so. Though my ability to mentor wanes when I have 
gotten busy, I have always prioritized helping out the newest contributors, 
letting other, more confident actors' emails slip if necessary. If I have 
erred, I am sorry.

"Don't be dismissive" is not an answer to my question, as it is both imprecise 
and not technical. The most recent thread indeed had posts that seemed quite 
dismissive, but these posts emanated from people with a variety of viewpoints. 
It was hardly GHC HQ (whatever that means). What, precisely, has been 
dismissed? It looks to me that we (regular GHC contributors) take the 
community's concerns seriously. Fixes may be slow in coming, but that's not 
dismissiveness. Of course I'm biased here, but I am truly and earnestly asking 
for clarification.

Emboldened by the technical, respectful discussion recently on the merits (and 
usage patterns) of stack (starting at 
https://mail.haskell.org/pipermail/haskell-cafe/2016-September/124847.html), I 
look forward to a similarly technical, respectful discussion on our 
contribution process.

Thanks for all that you (for all values of "you") do to help grow our community 
and make it stronger.

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>
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs