Re: [gentoo-dev] [RFC] Reinstating old-school GLEPs masterplan

[Michał Górny]

W dniu pon, 11.09.2017 o godzinie 21∶59 -0500, użytkownik R0b0t1
napisał:
> Hello friends,
>
> On Mon, Sep 11, 2017 at 3:56 PM, Michał Górny <mgorny@g.o> wrote:
> > W dniu pon, 11.09.2017 o godzinie 13∶29 -0400, użytkownik Michael
> > Orlitzky napisał:
> > > On 09/11/2017 01:08 PM, Michał Górny wrote:
> > > > Hi,
> > > >
> > > > TL;DR: I'd like to reinstate the old-school GLEPs in .rst files rather
> > > > than Wiki, put in a nice git repo.
> > > >
> > >
> > > I generally agree with you that wiki markup is terrible and that a text
> > > editor and a git repo is The Right Way to do things (with Jekyll or
> > > whatever to push it to the web). But in my experience, crappy and easy
> > > is a better way to get people to contribute. When I've taken wiki
> > > documents and moved them into git repos, more often than not I become
> > > the sole contributor, and otherwise-technical people just start emailing
> > > me their contributions (which decrease greatly in frequency).
> >
> > [...]
> >
> > Then, you can just take www.gentoo.org and run it locally. It takes
> > a little more effort but jekyll is really trivial to set up and run
> > locally. Then you see it exactly how it's gonna look on g.o.
> >

I'm going to reply to the Gollum topic here since it's the first mail
according to date.

> I previously suggested Gollum and think I should suggest it again.
> Gollum provides features relevant to a Wiki setting including web
> editing.

Firstly, a generic request to everyone. If you want to suggest that we
are supposed to use your-favorite-tool instead of the one we have
deployed for a few years now, then please include:

1. A short summary including:

1a. How it fits into the desired workflow. Topics such as access control
and caching are of particular interest to me.

1b. What possible future use it could have.

1c. How much effort will the future maintenance take.

2. A publicly available working instance that resembles the workflow
we're aiming for, or an easy way of setting one up. Easy = ~5 simple
shell commands, not 'set a webserver up'.

3. A statement from an Infra member that is willing to set the instance
up and maintain it.

Because otherwise we're only going to lose time on theoretical debates
over software without even knowing if it will work at all, do what it's
supposed to do, and most importantly, if someone will actually set
a production instance up and maintain it afterwards.

Infra already maintains enough diverse platforms/services/frameworks
that serve only a single tool selected by one person who used to like
it, and not maintained anymore. SMW belongs to that group.

>  It would not require pages be rewritten and can render
> MediaWiki that is maintained in a Git repository.

Secondly, even if Gollum supported MW markup to the point of rendering
GLEPs (which it doesn't [1]), MW markup is not suitable for any
technical specifications or serious documentation for two reasons:

a. MW markup is not proper WYWIWYG. Any more complex part of
the document is not readable as plaintext. Add to that the horrible
syntax requiring <nowiki> use mixed with inline HTML...

b. MW markup is not standalone. Our GLEPs already started heavily
depending on random templates (which can change at any time, breaking
GLEPs in the process btw).

> It should be all of the positives with no negatives.

Is it?


[1]:https://help.github.com/articles/supported-mediawiki-formats/

-- 
Best regards,
Michał Górny