Subject: Re: [alpine-devel] Improving Alpine Linux documentation
To: alpine-devel@lists.alpinelinux.org
References: <20171212201302.GA9334@eddy>
From: "A. Wilcox" <awilfox@adelielinux.org>
Organization: =?UTF-8?Q?Ad=c3=a9lie_Linux?=
Message-ID: <5A304BC7.3020401@adelielinux.org>
Date: Tue, 12 Dec 2017 15:36:07 -0600
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
 Thunderbird/38.5.0
Precedence: list
MIME-Version: 1.0
In-Reply-To: <20171212201302.GA9334@eddy>
Content-Type: text/plain; charset="windows-1252"
Content-Transfer-Encoding: quoted-printable

-----BEGIN PGP SIGNED MESSAGE-----
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:
>=20
> 2. We move the core project documentation somewhere else=20
> (https://alpinelinux.org or https://docs.alpinelinux.org) but keep=20
> Wiki in place for the community. This way the core project=20
> 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=E9lie.  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.

Best,
- --arw


- --=20
A. Wilcox (awilfox)
Project Lead, Ad=E9lie Linux
http://adelielinux.org
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJaMEvEAAoJEMspy1GSK50USF0P/0BtvmEXOzxD7mJWydJkHi6F
HHkx2nb5bsAhKxVif0h/k3qZMShyCbn2dS68+znuPPKRCouHXHUlCWoiLNdZY1Y7
rBqjmAMXZezBt7xgS4CflmCpeTofDWBBcJQzbqIHJhf8/j4KA8lYZii+/EpIhbGd
8Uz/z9ZRw52s8Tn052jV96QJXIkD3jt+Tuk9v3BptYta2RuWD9GgAd70T17BRUq3
ugqwcXUa58RbvtsxT0psDb2+xQwfN9b4eK0K+CsMYioC7icWMj5QhBg+bcUX1442
6/oJBngd7fUt2oAgEuG3xiOps0uN5kTmFvW+TDuyDy0v6TaH2GUeAWJNcOciFmNZ
tggjc1E15rTnt43KzUtN2oJc7vPXcaJL3NWb4WxFKOC3rhfnN+XjbBxthp911i9a
YXlMX9+zXKJidIaKW5GXy4VVwwvX4PbIENkbucptTa39NjEtG4JNzwXeF8noWiQZ
y1J7ED0P9U5sxefILR+ypqSMadrM8aknSEDF3V+1p2yT6o5FVOO4s+m0hLhJyAbA
fdpO0npamDxxR1fjrF4PVadzlGCYhUYuNacRIB1MV9m/6yfKt7xjM5y6mGeEMxiK
k+/6mt5myXIHbSW1YtPjb8hk/zDkEWroeco4Y83q4dRhn2wqHMO6LcN3Z9eKZtSr
/kLeL7TYRDIkZs3VSM0S
=3DJQlb
-----END PGP SIGNATURE-----


---
Unsubscribe:  alpine-devel+unsubscribe@lists.alpinelinux.org
Help:         alpine-devel+help@lists.alpinelinux.org
---