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

[R0b0t1]

Hello,

On Tue, Sep 12, 2017 at 9:04 AM, Michał Górny <mgorny@g.o> wrote:
> 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.
>

There is a thread in gentoo-dev where I proposed the Handbook be
maintained with Gollum. I apologize if it was not visible, but I was
trying to not make a nuisance of myself.

>> 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:
>

I believe I addressed all of these. Please make suggestions on my
writing so I can make it more readable if you have the time.

If I suggest a project I think it reasonable to expect you to refer to
that project's README. Here is a link:
https://github.com/gollum/gollum/blob/master/README.md.

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

It manages a Wiki using a Git repository. Access control is managed
through the Git repository and has Git's limitations. When using
Gollum it seems like access control is best done by creating
repositories. The web editor seems to lack authentication.

Gollum may have issues with caching[1]. Gollum is deployed by GitHub,
but most GitHub project Wikis may be small.

> 1b. What possible future use it could have.
>

It could maintain all public facing documents.

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

I do not see how it would take more maintenance time than Jekyll. It
may take less as it offers Wiki specific features.

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

The README offers concise instructions for setting up a demonstration
instance and scaling up. Should that be hard to read, a video is
available (https://www.youtube.com/watch?v=EauxgxsLDC4).

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

It seems like it is your burden to interpret the suggestion and refer
it to the people who would be maintaining it. If you don't want to
then that is fine.

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

It is not possible for me to know everything you would like addressed
in advance.

Most of the problems Gentoo faces are unique enough that I do not
think it is reasonable to expect a useful solution to exist. There
will always be problems.

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

Yes, I suppose the lack of templates might make it unusable.

I never meant to defend MW. It just might have been possible to avoid
rewriting many of the pages until absolutely necessary.

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

I don't know. You are the one with more information than me. I only
stated as much because it genuinely seems like it is; follow up on my
suggestion if it looks like it may initially be suitable.

Even large problems like the lack of real authentication do not really
make the situation any worse than it already is with controlled Wiki
pages. For more restricted pages it is likely irrelevant.

There was quite a bit of research involved in my original suggestion
of Gollum, however I didn't think to look at some of the points you
brought up. It looks like it might not be suitable. It also looks like
there may not be anything "suitable," really, though static website
generation may be the least intrusive.

Respectfully,
     R0b0t1


[1]: https://github.com/gollum/gollum/issues/1078