Mail archive
alpine-devel

Re: [alpine-devel] Improving Alpine Linux documentation

From: Stuart Cardall <developer_at_it-offshore.co.uk>
Date: Fri, 15 Dec 2017 20:23:39 +0000

I started creating README.alpine docs with notes to get things working:

musl64 [~/aports]$ find . -type f -name README.alpine
./community/elasticsearch/README.alpine
./community/runit/README.alpine
./community/lxcfs/README.alpine
./community/autossh/README.alpine
./community/mini-sendmail/README.alpine
./testing/pass/README.alpine

Stuart.


On 12/15/2017 08:12 AM, Natanael Copa wrote:
> On Tue, 12 Dec 2017 23:13:05 +0300
> Consus <consus_at_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_at_lists.alpinelinux.org
> Help: alpine-devel+help_at_lists.alpinelinux.org
> ---
>




---
Unsubscribe:  alpine-devel+unsubscribe_at_lists.alpinelinux.org
Help:         alpine-devel+help_at_lists.alpinelinux.org
---
Received on Fri Dec 15 2017 - 20:23:39 GMT