Reply-To: developer@it-offshore.co.uk
Subject: Re: [alpine-devel] Improving Alpine Linux documentation
To: alpine-devel@lists.alpinelinux.org
References: <20171212201302.GA9334@eddy>
 <20171215091236.324b290c@ncopa-desktop.copa.dup.pw>
From: Stuart Cardall <developer@it-offshore.co.uk>
Message-ID: <d15f7c25-b11e-e308-334e-dc09cb89c83c@it-offshore.co.uk>
Date: Fri, 15 Dec 2017 20:23:39 +0000
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101
 Thunderbird/52.4.0
Precedence: list
MIME-Version: 1.0
In-Reply-To: <20171215091236.324b290c@ncopa-desktop.copa.dup.pw>
Content-Type: multipart/alternative;
 boundary="------------5E5AD323D9E9F7B19C04D1C1"
Content-Language: en-US

This is a multi-part message in MIME format.
--------------5E5AD323D9E9F7B19C04D1C1
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit

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@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
> ---
>


--------------5E5AD323D9E9F7B19C04D1C1
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 7bit

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  </head>
  <body text="#000099" bgcolor="#FFFFFF">
    <p><font face="Helvetica, Arial, sans-serif">I started creating
        README.alpine docs with notes to get things working:</font></p>
    <p><font face="Helvetica, Arial, sans-serif">musl64 [~/aports]$ find
        . -type f -name README.alpine<br>
        ./community/elasticsearch/README.alpine<br>
        ./community/runit/README.alpine<br>
        ./community/lxcfs/README.alpine<br>
        ./community/autossh/README.alpine<br>
        ./community/mini-sendmail/README.alpine<br>
        ./testing/pass/README.alpine<br>
      </font></p>
    <p><font face="Helvetica, Arial, sans-serif">Stuart.</font><br>
    </p>
    <br>
    <div class="moz-cite-prefix">On 12/15/2017 08:12 AM, Natanael Copa
      wrote:<br>
    </div>
    <blockquote type="cite"
      cite="mid:20171215091236.324b290c@ncopa-desktop.copa.dup.pw">
      <pre wrap="">On Tue, 12 Dec 2017 23:13:05 +0300
Consus <a class="moz-txt-link-rfc2396E" href="mailto:consus@ftml.net">&lt;consus@ftml.net&gt;</a> wrote:

</pre>
      <blockquote type="cite">
        <pre wrap="">Hello,

I'm writing this email to start an archived discussion about the future
of the Alpine Linux documentation.
</pre>
      </blockquote>
      <pre wrap="">
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.

...

</pre>
      <blockquote type="cite">
        <pre wrap="">2. We move the core project documentation somewhere else
   (<a class="moz-txt-link-freetext" href="https://alpinelinux.org">https://alpinelinux.org</a> or <a class="moz-txt-link-freetext" href="https://docs.alpinelinux.org">https://docs.alpinelinux.org</a>) 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.
</pre>
      </blockquote>
      <pre wrap="">
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
(<a class="moz-txt-link-freetext" href="https://wiki.alpinelinux.org/wiki/Alpine_Linux:Releases">https://wiki.alpinelinux.org/wiki/Alpine_Linux:Releases</a>)

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
  (<a class="moz-txt-link-freetext" href="https://lists.alpinelinux.org/alpine-user/0205.html">https://lists.alpinelinux.org/alpine-user/0205.html</a>)

- Remove duplicates:
  <a class="moz-txt-link-freetext" href="https://wiki.alpinelinux.org/wiki/Alpine_Linux:Mailing_lists">https://wiki.alpinelinux.org/wiki/Alpine_Linux:Mailing_lists</a>
  <a class="moz-txt-link-freetext" href="https://wiki.alpinelinux.org/wiki/Alpine_Linux:IRC">https://wiki.alpinelinux.org/wiki/Alpine_Linux:IRC</a>

- Remove obsolete/outdated docs

- Write how to create good content on the wiki (something like
  <a class="moz-txt-link-freetext" href="https://wiki.archlinux.org/index.php/Help:Editing">https://wiki.archlinux.org/index.php/Help:Editing</a>)

- 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:  <a class="moz-txt-link-abbreviated" href="mailto:alpine-devel+unsubscribe@lists.alpinelinux.org">alpine-devel+unsubscribe@lists.alpinelinux.org</a>
Help:         <a class="moz-txt-link-abbreviated" href="mailto:alpine-devel+help@lists.alpinelinux.org">alpine-devel+help@lists.alpinelinux.org</a>
---

</pre>
    </blockquote>
    <br>
  </body>
</html>

--------------5E5AD323D9E9F7B19C04D1C1--


---
Unsubscribe:  alpine-devel+unsubscribe@lists.alpinelinux.org
Help:         alpine-devel+help@lists.alpinelinux.org
---