Dear Takenobu, may I politely direct you to https://github.com/ghc-proposals/ghc-proposals/pull/10, and ask you to add your comments there as well, as that proposal tries to track these changes in a central place through the new ghc-proposal process.
Cheers, Moritz > On Sep 30, 2016, at 6:56 PM, Takenobu Tani <takenobu...@gmail.com> wrote: > > Hi, > > Richard said: > (1) search engines still find out-of-date documentation > (2) the wiki is not discoverable > > I know trac is treasure house. > And I realized old pages are valuable for decision. > > > My concrete suggestion is here: > > For (1): > When we find out-of-date documentation, we directly modify head of the > document. > We manually insert a comment like "This content is out-of-date for GHC8.0". > (New contributors easy can do it.) > > For (2): > We provide manually-written multiple indexes for different views on a portal > page of the wiki site. > Contributors could maintain each index themselves. > (New comers will choose his favorite index for his exploring.) > > Furthermore, we provide a simple search box for multiple wiki sites. > (Please wait for a while. I'll prepare simple-conceptual demonstration with > web.) > > > Diversity is strength of Haskell community, > Takenobu > > > 2016-09-30 4:14 GMT+09:00 Richard Eisenberg <r...@cs.brynmawr.edu>: > I've spent some time thinking about how and what to synthesize from this > conversation. Moritz has captured much of these ideas in the proposal he > submitted. Thanks. > > But that proposal tackles only one part of the problem: what to do in the > future. It does not address the insufficiencies of the wiki as it now stands, > and these drawbacks seem to be the dangling fibers of this thread. Two > specific complaints are that (1) search engines still find out-of-date > documentation and (2) the wiki is not discoverable. I agree with both of > these, but I can't think of any (easy) way to help either one. > > For (1), the "obvious" solution is to pull old pages. However, old pages > still serve as useful documentary evidence when we need to revisit a decision > made in the past. I think simply deleting out-of-date pages may lose useful > info. Could we remove the pages from the wiki but keep them somewhere else, > beyond the all-seeing eye of Google? Perhaps -- but where? I wouldn't want to > keep it somewhere private, lest it be unavailable to the person that needs > it. I think clearly labeling out-of-date info as such is the best compromise. > > For (2), there is an index to the wiki: > https://ghc.haskell.org/trac/ghc/wiki/TitleIndex It's long and rambly, but > may be of use. I agree that grepping would be nice. Does anyone know if there > is a way to extract plaintext from a Trac wiki? I agree that making such a > feature available would be helpful. In the future, though, even a git-backed > collection will run into discoverability problems, unless someone continually > keeps it organized. (It will be greppable, though.) > > As to the point of shoring up existing infra vs. looking more broadly: I > suppose I am interesting in shoring up the existing infra, but I'm > considering "existing infra" to include all the platforms I'm aware of. This > explicitly includes the idea of dropping, say, Trac entirely and moving > exclusively to GitHub. I think that would be a terrible idea, but it's in > scope in my thinking. What's *not* in scope (in my thinking) is the idea of > creating new tools that do exactly what we want. We're all developers and can > imagine wonderful things, but wonderful things do not come cheaply, and we > are but poor. > > So I'm at a loss of what to do about these remaining fibers. Concrete > suggestions, anyone? > > Richard > > -=-=-=-=-=-=-=-=-=-=- > Richard A. Eisenberg > Asst. Prof. of Computer Science > Bryn Mawr College > Bryn Mawr, PA, USA > cs.brynmawr.edu/~rae > >> On Sep 29, 2016, at 7:37 AM, Takenobu Tani <takenobu...@gmail.com> wrote: >> >> Hi Carter, >> >> Thank you very much :) >> >> We love haskell, >> Takenobu >> >> >> 2016-09-28 22:29 GMT+09:00 Carter Schonwald <carter.schonw...@gmail.com>: >> I like your perspective on this >> >> >> On Wednesday, September 28, 2016, Takenobu Tani <takenobu...@gmail.com> >> wrote: >> Apologies if I’m missing context. >> >> >> Potential contributors need information from wiki. >> >> I feel current wiki’s problems are following: >> >> >> (a) reachability >> >> "Where is the page I need?" >> >> >> (b) outdated pages >> >> "Is this page up-to-date?" >> >> >> (c) update method >> >> "How Can I update the page?" >> >> >> >> About (a): >> >> >> It's difficult to find pages they need. Maybe reasons are following: >> >> * We have multiple wiki sites. >> >> * Desired contents structure is different for each member. >> >> >> So single wiki site is not enough from latter. >> >> >> Therefore, what about "a search system for multiple wiki sites"? >> >> >> >> About (b): >> >> >> Haskell's evolution is fast. >> >> New contributor encounters sometimes outdated pages. >> >> But they don't still know how to correct them. >> >> >> Therefore, what about putting "outdated mark" to the page by them? >> >> >> They can easily contribute. >> >> And if possible, they send update request with any way. >> >> We’ll preferentially update many requested pages. >> >> >> >> About (c): >> >> >> We have multiple wiki sites. Someone is unfamiliar about them. >> >> Github is one of the solutions for new contents. >> >> But I don't have idea about this for current contents. >> >> >> Regards, >> >> Takenobu >> >> >> >> 2016-09-28 10:51 GMT+09:00 Richard Eisenberg <r...@cs.brynmawr.edu>: >> I'm quite leery of using a new site (readthedocs.org), as it creates yet >> another platform for contributors to understand. Reducing the number of >> platforms has been a fairly clearly-stated goal of these recent >> conversations, as I've read it. >> >> Despite agreeing that wikis are sometimes wonky, I thought of a solid reason >> against moving: we lose the Trac integration. A Trac wiki page can easily >> link to tickets and individual comments, and can use dynamic features such >> as lists of active tickets. These are useful and well-used features. I don't >> know what's best here, but thinking about the real loss associated with >> moving away from these features gives me pause. >> >> Richard >> >> > On Sep 27, 2016, at 5:58 PM, Michael Sloan <mgsl...@gmail.com> wrote: >> > >> > On Tue, Sep 27, 2016 at 9:18 AM, Eric Seidel <e...@seidel.io> wrote: >> >> On Tue, Sep 27, 2016, at 09:06, Richard Eisenberg wrote: >> >>> Yes, I agree with Michael’s observations in the blog post. However, one >> >>> thing that’s easier about a wiki is that the editing process is much more >> >>> lightweight than making a PR. >> >>> >> >>> But GitHub has a wonderful feature (that I have rarely used) that >> >>> mitigates this problem. Viewing a file in GitHub offers a little pencil >> >>> icon in the top-right. It allows you to make arbitrary changes in the >> >>> file and then automates the construction of a PR. The owner of the file >> >>> can then accept the PR very, very easily. If the editor has commit >> >>> rights, you can make your edits into a commit right away. No need to >> >>> fork, pull and push. >> >> >> >> Indeed, GitHub also supports git-backed wikis, so you can have nicely >> >> rendered and inter-linked pages *and* have the option for web-based or >> >> git-based editing. Though, based on my limited experience with GitHub >> >> wikis, I wonder if they would scale to the size of GHC's wiki.. >> > >> > I agree, I don't think GitHub wikis are sufficient for GHC. We've >> > tried using GitHub wikis, and found that they were clunkier than just >> > having wiki / docs in your repo. GHC would probably want to have a >> > separate docs repo, as otherwise the commit history will get filled >> > with commits related to proposals, etc. >> > >> > It may be worth considering a similar approach with the GHC >> > documentation. We've had great success in stack with using >> > https://readthedocs.org/ . The way this works is that you have a >> > branch that readthedocs points at ("stable"), which provides the >> > current version to display. I realize that ghc would want to have >> > multiple versions of the docs up, but I'm sure that's feasible. >> > >> > Github itself has pretty nice markdown rendering, and the ability to >> > edit directly. Note that there is no GitHub lock-in here - it is just >> > a collection of markdown files, organized however you like them. >> > >> > The risk with such a migration is that the old wiki(s?) don't get >> > fully migrated and shut down. If that happens, then information will >> > be even more spread out and hard to find. Perhaps we can use pandoc >> > to automatically migrate much of the wiki content to markdown? It >> > probably will not be a lossfree conversion. >> > >> >> There's also a tool called gitit (https://github.com/jgm/gitit) that >> >> seems to offer the same set of features, but apparently with a more >> >> traditional (and I assume customizable) layout. >> >> >> >> I think having the option for simple, immediate edits or peer-reviewed >> >> edits (the peer-review is much more important to me than having an >> >> explicitly file-based system) would be a big win. Perhaps there's even a >> >> trac module that implements something like this? Then we could decouple >> >> it from the question/task of migrating the existing content elsewhere. >> >> >> >> Eric >> >> _______________________________________________ >> >> ghc-devs mailing list >> >> ghc-devs@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 >> >> > > > _______________________________________________ > 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 ————————————————— Moritz Angermann +49 170 54 33 0 74 mor...@lichtzwerge.de lichtzwerge GmbH Raiffeisenstr. 8 93185 Michelsneukirchen Amtsgericht Regensburg HRB 14723 Geschäftsführung: Moritz Angermann, Ralf Sangl USt-Id: DE291948767 Diese E-Mail enthält vertrauliche und/oder rechtlich geschützte Informationen. Wenn Sie nicht der richtige Adressat sind oder diese E-Mail irrtümlich erhalten haben, informieren Sie bitte sofort den Absender und vernichten Sie diese Mail. Das unerlaubte Kopieren sowie die unbefugte Weitergabe dieser Mail ist nicht gestattet. This e-mail may contain confidential and/or privileged information. If you are not the intended recipient (or have received this e-mail in error) please notify the sender immediately and destroy this e-mail. Any unauthorized copying, disclosure or distribution of the material in this e-mail is strictly forbidden. _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
