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

[Michał Górny]

W dniu sob, 16.09.2017 o godzinie 02∶51 -0500, użytkownik R0b0t1
napisał:
> 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.

That's what I suspected. So you're talking about deploying a wiki
without the basic feature of a wiki. IOW, once again deploying a tool
more complex than necessary, and working it around to make it work for
our purpose.

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

That's not an answer. Generating all GLEPs takes around 60 seconds right
now. With jekyll, that's done once. If gollum regenerates them
frequently, it's not a feasible solution.

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

There's a major difference between maintaining one tool we know, and two
tools (because obviously we won't dump Jekyll instantly), the second one
we don't know anything about.

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

That's not what I'm asking for. If it's that easy, then set it up.
What I want is a 'one click' solution that can get me running it without
major changes to my system, without effort on my end and in, say, less
than 5 minutes.

-- 
Best regards,
Michał Górny