How, precisely, can we improve?

Fri Sep 30 10:56:41 UTC 2016

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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20160930/8aa8cc21/attachment-0001.html>