How, precisely, can we improve?

Fri Sep 30 11:13:35 UTC 2016

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 <moritz at lichtzwerge.de>:

> 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.hs at 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 <rae at 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.hs at gmail.com>
> wrote:
> >>
> >> Hi Carter,
> >>
> >> Thank you very much :)
> >>
> >> We love haskell,
> >> Takenobu
> >>
> >>
> >> 2016-09-28 22:29 GMT+09:00 Carter Schonwald <carter.schonwald at gmail.com
> >:
> >> I like your perspective on this
> >>
> >>
> >> On Wednesday, September 28, 2016, Takenobu Tani <takenobu.hs at 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 <rae at 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 <mgsloan at gmail.com> wrote:
> >> >
> >> > On Tue, Sep 27, 2016 at 9:18 AM, Eric Seidel <eric at 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 at haskell.org
> >> >> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
> >> > _______________________________________________
> >> > ghc-devs mailing list
> >> > ghc-devs at haskell.org
> >> > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
> >>
> >> _______________________________________________
> >> ghc-devs mailing list
> >> ghc-devs at haskell.org
> >> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
> >>
> >>
> >
> >
> > _______________________________________________
> > ghc-devs mailing list
> > ghc-devs at haskell.org
> > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
> >
> >
> > _______________________________________________
> > ghc-devs mailing list
> > ghc-devs at haskell.org
> > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>
> —————————————————
> Moritz Angermann
> +49 170 54 33 0 74
> moritz at 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.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20160930/5587d2cf/attachment-0001.html>