I like your perspective on this<span></span><br><br>On Wednesday, September 28, 2016, Takenobu Tani <<a href="mailto:takenobu.hs@gmail.com">takenobu.hs@gmail.com</a>> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><p class="MsoNormal"><span lang="EN-US">Apologies if I’m missing context.</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US">Potential contributors need information
from wiki.</span></p>
<p class="MsoNormal"><span lang="EN-US">I feel current wiki’s problems are
following:</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US"> (a)
reachability</span></p>
<p class="MsoNormal"><span lang="EN-US">
"Where is the page I need?"</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US"> (b)
outdated pages</span></p>
<p class="MsoNormal"><span lang="EN-US">
"Is this page up-to-date?"</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US"> (c)
update method</span></p>
<p class="MsoNormal"><span lang="EN-US">
"How Can I update the page?"</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US">About (a):</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US">It's difficult to find pages they need.
Maybe reasons are following:</span></p>
<p class="MsoNormal"><span lang="EN-US"> *
We have multiple wiki sites.</span></p>
<p class="MsoNormal"><span lang="EN-US"> *
Desired contents structure is different for each member.</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US">So single wiki site is not enough from
latter.</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US">Therefore, what about "a search system for
multiple wiki sites"?</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US">About (b):</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US">Haskell's evolution is fast.</span></p>
<p class="MsoNormal"><span lang="EN-US">New contributor encounters sometimes
outdated pages.</span></p>
<p class="MsoNormal"><span lang="EN-US">But they don't still know how to correct
them.</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US">Therefore, what about putting
"outdated mark" to the page by them?</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US">They can easily contribute.</span></p>
<p class="MsoNormal"><span lang="EN-US">And if possible, they send update request
with any way.</span></p>
<p class="MsoNormal"><span lang="EN-US">We’ll preferentially update many requested
pages.</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US">About (c):</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US">We have multiple wiki sites. Someone is
unfamiliar about them.</span></p>
<p class="MsoNormal"><span lang="EN-US">Github is one of the solutions for new contents.</span></p>
<p class="MsoNormal"><span lang="EN-US">But I don't have idea about this for
current contents.</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p>
<p class="MsoNormal"><span lang="EN-US">Regards,</span></p>
<p class="MsoNormal"><span lang="EN-US">Takenobu</span></p>
<p class="MsoNormal"><span lang="EN-US"> </span></p></div><div class="gmail_extra"><br><div class="gmail_quote">2016-09-28 10:51 GMT+09:00 Richard Eisenberg <span dir="ltr"><<a href="javascript:_e(%7B%7D,'cvml','rae@cs.brynmawr.edu');" target="_blank">rae@cs.brynmawr.edu</a>></span>:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">I'm quite leery of using a new site (<a href="http://readthedocs.org" rel="noreferrer" target="_blank">readthedocs.org</a>), 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.<br>
<br>
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.<br>
<span><font color="#888888"><br>
Richard<br>
</font></span><div><div><br>
> On Sep 27, 2016, at 5:58 PM, Michael Sloan <<a href="javascript:_e(%7B%7D,'cvml','mgsloan@gmail.com');" target="_blank">mgsloan@gmail.com</a>> wrote:<br>
><br>
> On Tue, Sep 27, 2016 at 9:18 AM, Eric Seidel <<a href="javascript:_e(%7B%7D,'cvml','eric@seidel.io');" target="_blank">eric@seidel.io</a>> wrote:<br>
>> On Tue, Sep 27, 2016, at 09:06, Richard Eisenberg wrote:<br>
>>> Yes, I agree with Michael’s observations in the blog post. However, one<br>
>>> thing that’s easier about a wiki is that the editing process is much more<br>
>>> lightweight than making a PR.<br>
>>><br>
>>> But GitHub has a wonderful feature (that I have rarely used) that<br>
>>> mitigates this problem. Viewing a file in GitHub offers a little pencil<br>
>>> icon in the top-right. It allows you to make arbitrary changes in the<br>
>>> file and then automates the construction of a PR. The owner of the file<br>
>>> can then accept the PR very, very easily. If the editor has commit<br>
>>> rights, you can make your edits into a commit right away. No need to<br>
>>> fork, pull and push.<br>
>><br>
>> Indeed, GitHub also supports git-backed wikis, so you can have nicely<br>
>> rendered and inter-linked pages *and* have the option for web-based or<br>
>> git-based editing. Though, based on my limited experience with GitHub<br>
>> wikis, I wonder if they would scale to the size of GHC's wiki..<br>
><br>
> I agree, I don't think GitHub wikis are sufficient for GHC. We've<br>
> tried using GitHub wikis, and found that they were clunkier than just<br>
> having wiki / docs in your repo. GHC would probably want to have a<br>
> separate docs repo, as otherwise the commit history will get filled<br>
> with commits related to proposals, etc.<br>
><br>
> It may be worth considering a similar approach with the GHC<br>
> documentation. We've had great success in stack with using<br>
> <a href="https://readthedocs.org/" rel="noreferrer" target="_blank">https://readthedocs.org/</a> . The way this works is that you have a<br>
> branch that readthedocs points at ("stable"), which provides the<br>
> current version to display. I realize that ghc would want to have<br>
> multiple versions of the docs up, but I'm sure that's feasible.<br>
><br>
> Github itself has pretty nice markdown rendering, and the ability to<br>
> edit directly. Note that there is no GitHub lock-in here - it is just<br>
> a collection of markdown files, organized however you like them.<br>
><br>
> The risk with such a migration is that the old wiki(s?) don't get<br>
> fully migrated and shut down. If that happens, then information will<br>
> be even more spread out and hard to find. Perhaps we can use pandoc<br>
> to automatically migrate much of the wiki content to markdown? It<br>
> probably will not be a lossfree conversion.<br>
><br>
>> There's also a tool called gitit (<a href="https://github.com/jgm/gitit" rel="noreferrer" target="_blank">https://github.com/jgm/gitit</a>) that<br>
>> seems to offer the same set of features, but apparently with a more<br>
>> traditional (and I assume customizable) layout.<br>
>><br>
>> I think having the option for simple, immediate edits or peer-reviewed<br>
>> edits (the peer-review is much more important to me than having an<br>
>> explicitly file-based system) would be a big win. Perhaps there's even a<br>
>> trac module that implements something like this? Then we could decouple<br>
>> it from the question/task of migrating the existing content elsewhere.<br>
>><br>
>> Eric<br>
>> ______________________________<wbr>_________________<br>
>> ghc-devs mailing list<br>
>> <a href="javascript:_e(%7B%7D,'cvml','ghc-devs@haskell.org');" target="_blank">ghc-devs@haskell.org</a><br>
>> <a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs" rel="noreferrer" target="_blank">http://mail.haskell.org/cgi-bi<wbr>n/mailman/listinfo/ghc-devs</a><br>
> ______________________________<wbr>_________________<br>
> ghc-devs mailing list<br>
> <a href="javascript:_e(%7B%7D,'cvml','ghc-devs@haskell.org');" target="_blank">ghc-devs@haskell.org</a><br>
> <a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs" rel="noreferrer" target="_blank">http://mail.haskell.org/cgi-bi<wbr>n/mailman/listinfo/ghc-devs</a><br>
<br>
______________________________<wbr>_________________<br>
ghc-devs mailing list<br>
<a href="javascript:_e(%7B%7D,'cvml','ghc-devs@haskell.org');" target="_blank">ghc-devs@haskell.org</a><br>
<a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs" rel="noreferrer" target="_blank">http://mail.haskell.org/cgi-bi<wbr>n/mailman/listinfo/ghc-devs</a><br>
</div></div></blockquote></div><br></div>
</blockquote>