Re: [alpine-devel] Improving Alpine Linux documentation
I started creating README.alpine docs with notes to get things working:
musl64 [~/aports]$ find . -type f -name README.alpine
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:
>> I'm writing this email to start an archived discussion about the future
>> of the Alpine Linux documentation.
> 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
> 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
> 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
> 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
> - Remove duplicates:
> - Remove obsolete/outdated docs
> - Write how to create good content on the wiki (something like
> - 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)
> 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