Date: Tue, 12 Dec 2017 23:13:05 +0300
From: Consus <consus@ftml.net>
To: alpine-devel@lists.alpinelinux.org
Subject: [alpine-devel] Improving Alpine Linux documentation
Message-ID: <20171212201302.GA9334@eddy>
Mail-Followup-To: alpine-devel@lists.alpinelinux.org
Precedence: list
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

Hello,

I'm writing this email to start an archived discussion about the future
of the Alpine Linux documentation.

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.

For now the primary source of knowledge is the MediaWiki running on
https://wiki.alpinelinux.org. It does contain a lot of useful info,
however it lacks proper structure, the spam level is very high and
newcomers often get banned during the infamous grace period after the
account creation.

The other problem with the publicly edited Wiki (mentioned by Natanael)
is that one cannot fully trust the content. So malicious edits in Wiki
sections describing policies, BTC wallets for donations or secure
network configurations can harm the project. The question if existing
security methods (user groups with different permissions, ability to
lock a Wiki page) are enough to address this issue is open for
discussion.

We currently have (at least) three proposals:

1. The MediaWiki stays as it is (we just need to add the proper
   structure and harden it against the Evil Bot Horde).

2. We move the core project documentation somewhere else
   (https://alpinelinux.org or https://docs.alpinelinux.org) 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.

3. We completely move to some sort of https://docs.alpinelinux.org
   (no matter in it's current form or not) and all user contributions.
   Hardcore variant of #2.

Of course, every proposal have have it's own Pros and Cons.

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

It worth mentioning that the problems with Wiki can be addressed in a
number of ways.

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.

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.

Please, share your opinions on this topic so we can improve the state of
things.


---
Unsubscribe:  alpine-devel+unsubscribe@lists.alpinelinux.org
Help:         alpine-devel+help@lists.alpinelinux.org
---