<div dir="ltr"><div>Hi,</div><div><br></div><div>Richard said:</div><div>(1) search engines still find out-of-date documentation</div><div>(2) the wiki is not discoverable</div><div><br></div><div>I know trac is treasure house.</div><div>And I realized old pages are valuable for decision.</div><div><br></div><div><br></div><div>My concrete suggestion is here:</div><div><br></div><div>For (1):</div><div>When we find out-of-date documentation, we directly modify head of the document.</div><div>We manually insert a comment like "This content is out-of-date for GHC8.0".</div><div>(New contributors easy can do it.)</div><div><br></div><div>For (2):</div><div>We provide manually-written multiple indexes for different views on a portal page of the wiki site.</div><div>Contributors could maintain each index themselves.</div><div>(New comers will choose his favorite index for his exploring.)</div><div><br></div><div>Furthermore, we provide a simple search box for multiple wiki sites.</div><div>(Please wait for a while. I'll prepare simple-conceptual demonstration with web.)</div><div><br></div><div><br></div><div>Diversity is strength of Haskell community,</div><div>Takenobu</div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">2016-09-30 4:14 GMT+09:00 Richard Eisenberg <span dir="ltr"><<a href="mailto: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"><div style="word-wrap:break-word"><div>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.</div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>For (2), there is an index to the wiki: <a href="https://ghc.haskell.org/trac/ghc/wiki/TitleIndex" target="_blank">https://ghc.haskell.org/<wbr>trac/ghc/wiki/TitleIndex</a> 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.)</div><div><br></div><div>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.</div><div><br></div><div>So I'm at a loss of what to do about these remaining fibers. Concrete suggestions, anyone?</div><span class="HOEnZb"><font color="#888888"><div><br></div><div>Richard</div></font></span><span class=""><br><div>
<div>-=-=-=-=-=-=-=-=-=-=-<br>Richard A. Eisenberg<br>Asst. Prof. of Computer Science<br>Bryn Mawr College<br>Bryn Mawr, PA, USA<br><a href="http://cs.brynmawr.edu/~rae" target="_blank">cs.brynmawr.edu/~rae</a></div>
</div>
<br></span><div><div class="h5"><div><blockquote type="cite"><div>On Sep 29, 2016, at 7:37 AM, Takenobu Tani <<a href="mailto:takenobu.hs@gmail.com" target="_blank">takenobu.hs@gmail.com</a>> wrote:</div><br class="m_-2772772807736065461Apple-interchange-newline"><div><div dir="ltr"><div>Hi Carter,</div><div><br></div><div>Thank you very much :)</div><div><br></div><div>We love haskell,</div><div>Takenobu</div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">2016-09-28 22:29 GMT+09:00 Carter Schonwald <span dir="ltr"><<a href="mailto:carter.schonwald@gmail.com" target="_blank">carter.schonwald@gmail.com</a>></span>:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">I like your perspective on this<div class="m_-2772772807736065461HOEnZb"><div class="m_-2772772807736065461h5"><span></span><br><br>On Wednesday, September 28, 2016, Takenobu Tani <<a href="mailto:takenobu.hs@gmail.com" target="_blank">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><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><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><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><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><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><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><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><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><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><p class="MsoNormal"><span lang="EN-US">About (a):</span></p><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><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><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><p class="MsoNormal"><span lang="EN-US">So single wiki site is not enough from
latter.</span></p><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><p class="MsoNormal"><span lang="EN-US">Therefore, what about "a search system for
multiple wiki sites"?</span></p><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><p class="MsoNormal"><span lang="EN-US">About (b):</span></p><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><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><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><p class="MsoNormal"><span lang="EN-US">Therefore, what about putting
"outdated mark" to the page by them?</span></p><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><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><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><p class="MsoNormal"><span lang="EN-US">About (c):</span></p><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><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><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div><p class="MsoNormal"><span lang="EN-US">Regards,</span></p><p class="MsoNormal"><span lang="EN-US">Takenobu</span></p><div><span lang="EN-US"> </span><br class="m_-2772772807736065461webkit-block-placeholder"></div></div><div class="gmail_extra"><br><div class="gmail_quote">2016-09-28 10:51 GMT+09:00 Richard Eisenberg <span dir="ltr"><<a>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>mgsloan@gmail.com</a>> wrote:<br>
><br>
> On Tue, Sep 27, 2016 at 9:18 AM, Eric Seidel <<a>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>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>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>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>
</div></div></blockquote></div><br></div>
</div></blockquote></div><br></div></div></div><br>______________________________<wbr>_________________<br>
ghc-devs mailing list<br>
<a href="mailto:ghc-devs@haskell.org">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-<wbr>bin/mailman/listinfo/ghc-devs</a><br>
<br></blockquote></div><br></div>