Date: Fri, 15 Dec 2017 09:12:36 +0100
From: Natanael Copa <ncopa@alpinelinux.org>
To: Consus <consus@ftml.net>
Cc: alpine-devel@lists.alpinelinux.org
Subject: Re: [alpine-devel] Improving Alpine Linux documentation
Message-ID: <20171215091236.324b290c@ncopa-desktop.copa.dup.pw>
In-Reply-To: <20171212201302.GA9334@eddy>
References: <20171212201302.GA9334@eddy>
Precedence: list
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit

On Tue, 12 Dec 2017 23:13:05 +0300
Consus <consus@ftml.net> wrote:

> Hello,
> 
> I'm writing this email to start an archived discussion about the future
> of the Alpine Linux documentation.

Hi!

Thank you for bringing this up. I agree that we need to improve
documentation and I have been thinking about it for a while.

...

> 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.

This is the solution I would like to go for, that is, some of the
official documentation is moved out from mediawiki to something else,
like docs.alpinelinux.org and manpages, while much of the docs stays on
wiki.

We need to keep in mind that there are different kinds of
documentation. For example:

install doc: how to do the install
administrator doc: the overview doc on how to do basic things in alpine
manpages: technical docs and specifications for individual tools
contributor doc: how to get involved in the project
developer doc: how to get started with development
infra doc: documentation of our infra structure
community docs: how to set up some specific hard/software


If you are first time user of alpine, and wonder how to get started,
then man pages may not be that helpful. You need an install doc that
can guide you throught the install. What is the difference between
sys/data/diskless install? When do you use what?

After the install is done, the user may need some guidance to do the
basic admin stuff, like (re)configure network, add users, change
password, find and install software, start and stop services.

Those docs can link to the manpages, which are more in-depth docs for
each tool. I don't have strong opinion on the format of the man pages.
Personally I would prefer write things in markdown or asciidoc, but I
don't mind writing directly in mdoc. (would be nice to have a filter
for cgit to parse mdoc)

The contributor and developer docs includes the Alpine linux project
processes and policies. How do you report bugs? How do you submit
patches? How do we include new developers? How do you become an aports
maintainer? How/when do new developers get git push access? What do we
do when someone leaves? How do a developer tag a new Alpine release?
Who are on the infra team? Who are the core developers? How/when are
releases made?

The community docs are things like, how do I get this USB wifi dongle
to work under alpine? How to install and set up apache, nginx, postfix
etc.


The question is now, how much of the above do we keep in wiki and how
much do we move out from wiki?

I think that manpages should be kept in the project it belongs to (eg
apk man pages should be stored in the apk-tools git repo, etc).

I think we should move things that are policies out of wiki too, things
like how to become a developer, how to contribute monetary, how the
release process works
(https://wiki.alpinelinux.org/wiki/Alpine_Linux:Releases)

I also don't think we can expect to move everything out from wiki and
moving things will take time. So we need to keep the wiki in good shape.

What I think we should do with the wiki:

- fix the registration process for new users
  (https://lists.alpinelinux.org/alpine-user/0205.html)

- Remove duplicates:
  https://wiki.alpinelinux.org/wiki/Alpine_Linux:Mailing_lists
  https://wiki.alpinelinux.org/wiki/Alpine_Linux:IRC

- Remove obsolete/outdated docs

- Write how to create good content on the wiki (something like
  https://wiki.archlinux.org/index.php/Help:Editing)

- Update the style/css?


I think that would be a good start at least.

What documentation is currently missing?

Other thing I think we should do is to make sure that every git repo
has a README, which includes:
- what is the purpose of the software project
- how do you get started (how to build)
- where to find info on how to report bugs and get involved (links)

Thanks!

-nc


---
Unsubscribe:  alpine-devel+unsubscribe@lists.alpinelinux.org
Help:         alpine-devel+help@lists.alpinelinux.org
---