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 <[email protected]>: > 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 <[email protected]> > 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 <[email protected]>: > > 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 <[email protected]> > wrote: > >> > >> Hi Carter, > >> > >> Thank you very much :) > >> > >> We love haskell, > >> Takenobu > >> > >> > >> 2016-09-28 22:29 GMT+09:00 Carter Schonwald <[email protected] > >: > >> I like your perspective on this > >> > >> > >> On Wednesday, September 28, 2016, Takenobu Tani <[email protected]> > 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 <[email protected]>: > >> 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 <[email protected]> wrote: > >> > > >> > On Tue, Sep 27, 2016 at 9:18 AM, Eric Seidel <[email protected]> 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 > >> >> [email protected] > >> >> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs > >> > _______________________________________________ > >> > ghc-devs mailing list > >> > [email protected] > >> > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs > >> > >> _______________________________________________ > >> ghc-devs mailing list > >> [email protected] > >> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs > >> > >> > > > > > > _______________________________________________ > > ghc-devs mailing list > > [email protected] > > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs > > > > > > _______________________________________________ > > ghc-devs mailing list > > [email protected] > > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs > > ————————————————— > Moritz Angermann > +49 170 54 33 0 74 > [email protected] > > lichtzwerge GmbH > Raiffeisenstr. 8 > 93185 Michelsneukirchen > > Amtsgericht Regensburg HRB 14723 > Geschäftsführung: Moritz Angermann, Ralf Sangl > USt-Id: DE291948767 > > Diese E-Mail enthält vertrauliche und/oder rechtlich geschützte > Informationen. Wenn Sie nicht der richtige Adressat sind oder diese > E-Mail irrtümlich erhalten haben, informieren Sie bitte sofort den > Absender und vernichten Sie diese Mail. > Das unerlaubte Kopieren sowie die unbefugte Weitergabe dieser Mail > ist nicht gestattet. > This e-mail may contain confidential and/or privileged information. > If you are not the intended recipient (or have received this e-mail in > error) please notify the sender immediately and destroy this e-mail. > Any unauthorized copying, disclosure or distribution of the material in > this e-mail is strictly forbidden. > >
_______________________________________________ ghc-devs mailing list [email protected] http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
