Mail archive

Re: [alpine-devel] Improving Alpine Linux documentation

From: A. Wilcox <>
Date: Tue, 12 Dec 2017 15:36:07 -0600

Hash: SHA256

On 12/12/17 14:13, Consus wrote:
> Earlier this day we (clandmeter, _ikke_, ncopa, TBK and your
> humble author) were discussing on IRC (check out the new
> #alpine-docs channel) how the current state of the project
> documentation can be improved.

Is this channel available on Matrix as well?

> We currently have (at least) three proposals:
> 2. We move the core project documentation somewhere else
> ( or but keep
> Wiki in place for the community. This way the core project
> documentation is stored somewhere safe (probably in Git) and
> GitHub pull-requests or patches via ML are used to update it.

This is how we do it in Adélie. It seems to work well.

> The main concern with Git-based documentation solutions is that
> the standalone patch review system should be rolled out
> (patchworks, ReviewBoard, you name it) because as (AFAIK)
> clandmeter stated we cannot fully rely on GitHub. However, it gives
> the developers the full control over the content

I'm glad that Alpine core still realises that. I have been worried
lately that there is too much buy-in to GitHub from the Alpine
developers. Do we really want all of that valuable discussion about
PRs and such locked away in a corporation's databases? How long will
GitHub stay afloat before turning to ads, pay-to-use, or even just
plain disappear from the Internet?

> First of all, currently Alpine Wiki does not require a email
> address to create an account. Requiring a validated email address
> should reduce the spam level considerably.

Reduce, but not eliminate. Honestly, the only true way to eliminate
spam is to have closed registrations (you have to poke an Alpine
person to get an account on the wiki). But that adds a lot of work,
so it probably isn't a good solution. Requiring valid email will take
out 80% of it so I suppose that's a very good start.

> Sensitive information (like PGP keys, donation options, etc) stored
> in the Wiki can be restricted for developer accounts only. If user
> finds an error in the document he can raise an issue in the
> Discussion tab.

I don't think any of this should be stored on the wiki. All of this
should be on the main site, and never on the Wiki. It certainly won't
change very often, so there's no reason to need for the community to
be able to edit it.

Meanwhile, I am going to work on mdoc'ing up apk and friends and hope
to have this done by the weekend.

- --arw

- --
A. Wilcox (awilfox)
Project Lead, Adélie Linux
Version: GnuPG v2


Received on Tue Dec 12 2017 - 15:36:07 UTC