How, precisely, can we improve?
Herbert Valerio Riedel
hvriedel at gmail.com
Thu Sep 29 07:10:44 UTC 2016
On 2016-09-28 at 03:51:22 +0200, Richard Eisenberg wrote:
> 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
I'd like to emphasize this point; Trac's main strength, design
philosophy, and selling point is its tight integration between SCM, Wiki
and Issue tracking and resulting synergies (same markup features,
extensions, syntax usable seamless), whereas the issue tracking part is
its strongest feature.
If you rip away its Wiki (and replace it by something
decoupled/non-integrated as e.g. GitHub's Git-backed Wiki), you
weaken it to the point where it becomes quite harder to argue to keep
Trac at all. It's already sub-optimal we spread discussions/information
across Trac and Phabricator (you often have to read both, the Diff
discussions and the associated Trac ticket discussion to get the full
picture); I doubt a 3rd more or less isolated tool which weakens
cohesion would improve things.
: Personally, I consider GitHub's Wiki quite weak and inconvenient
to use. It's stylesheet is not as optimised as Trac's and
structuring the content is also significantly worse than with
Trac. And finally GH-flavoured Markdown is very limiting compared
to Trac's rich extensible wiki syntax; Github's Wiki doesn't even
recognize #123 or Git-shas like 993d20a2e9b8fb29a (and then
provide mouse-over hoover texts with a title of the respective
referenced commit or ticket); you have to paste full urls and
manually include a title.
So IMO Github's wiki is not suitable for GHC's use at all.
A highly customized/forked Gitit instance, however, may be a more
reasonable alternative, but then the question is who is gonna
customize, implement and maintain it. Or we can drop the idea of a
wiki altogether, and go for statically generated docs. Then we
could just keep the wiki-content as restructedText (which btw is
more expressive and extensible than .md) and have sphinx generated
output. But then that's a totally different medium compared to a
However, I'm still missing a compelling reason in this discussion
to justify the cost of changing the status-quo.
More information about the ghc-devs