How, precisely, can we improve?

[Herbert Valerio Riedel]

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
> pause.

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[1]), 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.


 [1]: 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
      Wiki...

      However, I'm still missing a compelling reason in this discussion
      to justify the cost of changing the status-quo.